// Package protocol provides bounded, multiplexed JSON RPC over inherited pipes. package protocol import ( "bufio" "context" "encoding/binary" "encoding/json" "errors" "io" "sync" "sync/atomic" "time" "clusterflow.dev/cfbrowser/api" ) // FeatureVersion changes when SDK/worker operations must be deployed together. const FeatureVersion = 2 const Version = 1 const MaxMessage = 512 * 1024 type Request struct { Version int `json:"version"` ID uint64 `json:"id"` Method string `json:"method"` Deadline int64 `json:"deadline,omitempty"` Params json.RawMessage `json:"params,omitempty"` } type Response struct { Version int `json:"version"` ID uint64 `json:"id"` Result json.RawMessage `json:"result,omitempty"` Error *api.Error `json:"error,omitempty"` } func Read(r io.Reader, v any) error { var header [4]byte if _, e := io.ReadFull(r, header[:]); e != nil { return e } n := binary.BigEndian.Uint32(header[:]) if n == 0 || n > MaxMessage { return api.Err("BROWSER_PROTOCOL_LIMIT", "invalid message length") } b := make([]byte, n) if _, e := io.ReadFull(r, b); e != nil { return e } return json.Unmarshal(b, v) } func Write(w io.Writer, v any) error { b, err := json.Marshal(v) if err != nil { return err } if len(b) > MaxMessage { return api.Err("BROWSER_PROTOCOL_LIMIT", "message exceeds 512 KiB") } var header [4]byte binary.BigEndian.PutUint32(header[:], uint32(len(b))) if err = writeAll(w, header[:]); err != nil { return err } return writeAll(w, b) } func writeAll(w io.Writer, b []byte) error { for len(b) > 0 { n, e := w.Write(b) if e != nil { return e } if n <= 0 { return io.ErrShortWrite } b = b[n:] } return nil } type Client struct { r io.Reader w io.Writer writeMu sync.Mutex mu sync.Mutex pending map[uint64]chan Response seq atomic.Uint64 done chan struct{} closeOnce sync.Once } func NewClient(r io.Reader, w io.Writer) *Client { c := &Client{r: r, w: w, pending: map[uint64]chan Response{}, done: make(chan struct{})} go c.readLoop() return c } func (c *Client) Close() { c.closeOnce.Do(func() { close(c.done) }) } func (c *Client) readLoop() { defer c.Close() r := bufio.NewReader(c.r) for { var response Response if e := Read(r, &response); e != nil || response.Version != Version { return } c.mu.Lock() ch := c.pending[response.ID] c.mu.Unlock() if ch != nil { select { case ch <- response: default: } } } } func (c *Client) send(request Request) error { c.writeMu.Lock() defer c.writeMu.Unlock() return Write(c.w, request) } func (c *Client) Call(ctx context.Context, method string, args, out any) error { if err := ctx.Err(); err != nil { return err } params, err := json.Marshal(args) if err != nil { return err } id := c.seq.Add(1) ch := make(chan Response, 1) c.mu.Lock() if len(c.pending) >= 32 { c.mu.Unlock() return api.Err("BROWSER_LIMIT", "too many pending worker requests") } c.pending[id] = ch c.mu.Unlock() defer func() { c.mu.Lock(); delete(c.pending, id); c.mu.Unlock() }() request := Request{Version: Version, ID: id, Method: method, Params: params} if d, ok := ctx.Deadline(); ok { request.Deadline = d.UnixMilli() } select { case <-c.done: return api.Err("BROWSER_WORKER_EXITED", "worker connection closed") default: } if err = c.send(request); err != nil { return err } select { case r := <-ch: if r.Error != nil { switch r.Error.Code { case "BROWSER_CANCELED": r.Error.Cause = context.Canceled case "BROWSER_TIMEOUT": r.Error.Cause = context.DeadlineExceeded } return r.Error } if out == nil { return nil } return json.Unmarshal(r.Result, out) case <-c.done: return api.Err("BROWSER_WORKER_EXITED", "worker connection closed") case <-ctx.Done(): // Cancellation is advisory; a dispatched action may already have taken effect. go func() { _ = c.send(Request{Version: Version, ID: c.seq.Add(1), Method: "request.cancel", Params: json.RawMessage([]byte(`{"id":` + itoa(id) + `}`))}) }() return ctx.Err() } } func itoa(n uint64) string { b, _ := json.Marshal(n); return string(b) } type Handler func(context.Context, string, json.RawMessage) (any, error) // Serve bounds concurrency and cancels all handlers when the input closes. func Serve(ctx context.Context, r io.Reader, w io.Writer, handler Handler) error { ctx, cancel := context.WithCancel(ctx) defer cancel() var mu, writeMu sync.Mutex pending := map[uint64]context.CancelFunc{} var wg sync.WaitGroup if closer, ok := r.(io.Closer); ok { stop := context.AfterFunc(ctx, func() { _ = closer.Close() }) defer stop() } defer func() { mu.Lock() for _, stop := range pending { stop() } mu.Unlock() wg.Wait() }() respond := func(request Request, result any, err error) { response := Response{Version: Version, ID: request.ID} if err != nil { var typed *api.Error if errors.Is(err, context.Canceled) { response.Error = &api.Error{Code: "BROWSER_CANCELED", Message: "request canceled"} } else if errors.Is(err, context.DeadlineExceeded) { response.Error = &api.Error{Code: "BROWSER_TIMEOUT", Message: "request deadline exceeded"} } else if errors.As(err, &typed) { response.Error = typed } else { response.Error = &api.Error{Code: "BROWSER_WORKER_ERROR", Message: err.Error()} } } else { response.Result, _ = json.Marshal(result) } writeMu.Lock() defer writeMu.Unlock() if e := Write(w, response); e != nil { cancel() } } for { var req Request err := Read(r, &req) if err == io.EOF { return nil } if err != nil { return err } if req.Version != Version || req.ID == 0 { respond(req, nil, api.Err("BROWSER_PROTOCOL_VERSION", "unsupported protocol envelope")) continue } if req.Method == "request.cancel" { var a struct { ID uint64 `json:"id"` } _ = json.Unmarshal(req.Params, &a) mu.Lock() stop := pending[a.ID] mu.Unlock() if stop != nil { stop() } respond(req, true, nil) continue } mu.Lock() if pending[req.ID] != nil || len(pending) >= 32 { mu.Unlock() respond(req, nil, api.Err("BROWSER_LIMIT", "duplicate ID or concurrency limit")) continue } call, stop := context.WithCancel(ctx) if req.Deadline > 0 { var deadlineCancel context.CancelFunc call, deadlineCancel = context.WithDeadline(call, time.UnixMilli(req.Deadline)) old := stop stop = func() { deadlineCancel(); old() } } pending[req.ID] = stop mu.Unlock() wg.Add(1) go func(req Request, call context.Context, stop context.CancelFunc) { defer wg.Done() defer stop() defer func() { mu.Lock(); delete(pending, req.ID); mu.Unlock() }() result, err := handler(call, req.Method, req.Params) respond(req, result, err) }(req, call, stop) } }