xhttp

README

cs http

HTTP 适配器，该适配器支持请求响应模式，服务端推送使用 SSE(Server-Sent Event)，所以需要客户端支持，会话 sid 使用 cookie 做保持

数据协议

请求响应

请求响应模式只能通过 POST, PUT, DELETE 方法发起，因为只有这些请求才能在 HTTP BODY 放数据，数据类型是 json，遵循以下格式 ，对 http header 的 Content-Type 没有要求，无论设置成什么值，都会以 json 去解析 body 数据

请求json

{
  "cmd":"register",
  "seqno":"unique_string",
  "data": {}
}

• cmd 表示命令名，对应 cs 的路由
• seqno 表示该请求的唯一标识，在响应中会原样返回
• data 表示请求数据，可以是任意值，如 string, number, object, array, null

响应

{
  "cmd":"register",
  "seqno":"unique_string",
  "code": 0,
  "msg":"ok",
  "data": {}
}

• cmd 表示命令名，对应请求的 cmd
• seqno 表示该请求的唯一标识，对应请求的 seqno
• code 响应状态码，不等于 0 表示异常， -1 表示不支持请求的cmd，其他业务码根据业务适应
• msg 响应说明，只在code不等于 0 时才有意义
• data 表示响应数据，可能是任意值，如 string, number, object, array, null

服务器推送

客户端通过 EventSource 连接上时必须要带上 Cookie，因为使用 Cookie 作为会话记录，否则将无法推送至对应客户端

使用示例

import (
  "net/http"
  "github.com/eyasliu/cs"
  "github.com/eyasliu/cs/xhttp"
)

func main() {
  server := xhttp.New()
  http.Handle("/cmd", server)
  http.HandleFunc("/cmd1", server.Handler)
  srv := server.Srv()
  // http 不需要 srv.Run()

  log.Fatal(http.ListenAndServe(":8080", nil))
}

• 该适配器是不需要调用 srv.Run()，事实上即使调用了也不会有异常，会启动一个无用的 goroutine, 并且您将无法关闭它
• server 实现了 net/http 标准库的 http.Handler 接口，server.Handler 实现了 http.HandlerFunc，所以可以方便的用在其他 web 框架中

客户端在使用的时候

$ curl -XPOST --data '{"cmd":"register", "seqno": "unique_string", "data":{"name": "eyasliu"}}' http://127.0.0.1:8080/cmd
{"cmd":"register","seqno": "unique_string","code":0,"msg":"ok","data":{"timestamp": 1610960488}}

Documentation

Index

• Constants
• type Config
• type HTTP
  • func New() *HTTP
  • func (h *HTTP) Close(sid string) error
  • func (h *HTTP) GetAllSID() []string
  • func (h *HTTP) Handler(w http.ResponseWriter, req *http.Request)
  • func (h *HTTP) Read(srv *cs.Srv) (sid string, req *cs.Request, err error)
  • func (h *HTTP) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (h *HTTP) Srv() *cs.Srv
  • func (h *HTTP) Write(sid string, resp *cs.Response) error
• type SSEConn
  • func (s *SSEConn) Send(v ...*cs.Response) error
• type SSEMsgType

Constants

const (
	SSEEvent   = 0 // 使用事件, cmd 和 data 分开
	SSEMessage = 1 // 使用消息, cmd 和 data 都放到sse 的 data 域
)

Types

type Config

type Config struct {
	MsgType       SSEMsgType    // 消息类型
	HeartbeatTime time.Duration // SSE 心跳时长
	SIDKey        string        // sid 的 cookie key 名称
}

Config 配置项

type HTTP

type HTTP struct {
	// contains filtered or unexported fields
}

HTTP cs 的 HTTP 适配器

func New

func New() *HTTP

New 实例化适配器

func (*HTTP) Close

func (h *HTTP) Close(sid string) error

Close 实现 cs.ServerAdapter 接口，关闭指定连接

func (*HTTP) GetAllSID

func (h *HTTP) GetAllSID() []string

GetAllSID 实现 cs.ServerAdapter 接口，获取当前服务所有SID，用于遍历连接

func (*HTTP) Handler

func (h *HTTP) Handler(w http.ResponseWriter, req *http.Request)

Handler impl http.HandlerFunc to handler http request

func (*HTTP) Read

func (h *HTTP) Read(srv *cs.Srv) (sid string, req *cs.Request, err error)

Read 实现 cs.ServerAdapter 接口，读取消息，每次返回一条，循环读取

func (*HTTP) ServeHTTP

func (h *HTTP) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP impl http.Handler to handler http request

func (*HTTP) Srv

func (h *HTTP) Srv() *cs.Srv

Srv 返回cs.Srv 实例，如果没有绑定实例则初始化一个

func (*HTTP) Write

func (h *HTTP) Write(sid string, resp *cs.Response) error

Write 实现 cs.ServerAdapter 接口，给连接推送消息

type SSEConn

type SSEConn struct {
	// contains filtered or unexported fields
}

SSEConn SSE 的连接实例

func (*SSEConn) Send

func (s *SSEConn) Send(v ...*cs.Response) error

Send 给 sse 连接推送数据

type SSEMsgType

type SSEMsgType byte

SSEMsgType SSE 的消息时间模式