Something went wrong. Try again.
Cloudflare Cap'n'Web Go implementation
Something went wrong. Try again.
capnweb-go session.go
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837package capnweb
import ( "context" "encoding/json" "errors" "fmt" "math" "reflect" "sync")
// Session manages a single capnweb RPC connection. It is fully bidirectional —// either side can call methods on objects exported by the other.type Session struct { transport Transport imports *ImportTable exports *ExportTable
mu sync.Mutex pending map[int64]*pendingCall remoteImportID int64 // mirrors the remote's import ID allocation err error wg sync.WaitGroup // tracks in-flight push goroutines
// sendMu serializes outbound push/stream messages so that the implicit // import ID assignment (based on send order) stays in sync. Allocate must // happen inside this lock. sendMu sync.Mutex
ctxMu sync.RWMutex ctx context.Context cancel context.CancelFunc done chan struct{}}
type pendingCall struct { future *Future}
// NewSession creates a session. The main object is exported at ID 0 (the// bootstrap interface). Pass nil if this endpoint has no bootstrap.func NewSession(transport Transport, main any) *Session { ctx, cancel := context.WithCancel(context.Background()) return &Session{ transport: transport, imports: NewImportTable(), exports: NewExportTable(main), pending: make(map[int64]*pendingCall), done: make(chan struct{}), ctx: ctx, cancel: cancel, }}
// Main returns a Stub for the remote's bootstrap (main) interface.// This is the entry point for calling methods on the remote endpoint.func (s *Session) Main() *Stub { return newStub(s, 0)}
// wrapImportEntry converts *ImportEntry values to *Stub. If val is not// an *ImportEntry, it is returned unchanged.func (s *Session) wrapImportEntry(val any) any { if entry, ok := val.(*ImportEntry); ok { return newStub(s, entry.ID) } if slice, ok := val.([]any); ok { for i, elem := range slice { if entry, ok := elem.(*ImportEntry); ok { slice[i] = newStub(s, entry.ID) } } } return val}
// Run starts the message processing loop. It blocks until the context is// cancelled, the transport closes, or an abort is received.func (s *Session) Run(ctx context.Context) error { s.ctxMu.Lock() s.cancel() // cancel the background context from NewSession s.ctx, s.cancel = context.WithCancel(ctx) s.ctxMu.Unlock()
defer func() { s.cancel() close(s.done) }()
for { msg, err := s.transport.Recv(s.getCtx()) if err != nil { // Wait for in-flight goroutines before terminating // (e.g., batch transport returns EOF after all messages). s.wg.Wait() s.terminateAll(fmt.Errorf("capnweb: transport: %w", err)) return err } if err := s.handleMessage(msg); err != nil { s.wg.Wait() s.terminateAll(err) return err } }}
// Call sends a method call to a remote object and blocks until the result// is available. targetID is the import ID of the remote object (0 for the// bootstrap interface).func (s *Session) Call(ctx context.Context, targetID int64, method string, args ...any) (any, error) { return s.callWithTag(ctx, "import", targetID, method, args...)}
func (s *Session) callWithTag(ctx context.Context, tag string, targetID int64, method string, args ...any) (any, error) { expr, err := buildCallExpr(tag, targetID, method, args) if err != nil { return nil, err }
// Allocate + send must be atomic: the remote assigns implicit import IDs // in push-receive order, so our allocate order must equal our send order. f := NewFuture()
s.sendMu.Lock() entry := s.imports.Allocate() s.mu.Lock() s.pending[entry.ID] = &pendingCall{future: f} s.mu.Unlock() pushErr := s.transport.Send(ctx, PushMsg{Expr: expr}) pullErr := s.transport.Send(ctx, PullMsg{ImportID: entry.ID}) s.sendMu.Unlock()
if pushErr != nil { return nil, fmt.Errorf("capnweb: send push: %w", pushErr) } if pullErr != nil { return nil, fmt.Errorf("capnweb: send pull: %w", pullErr) }
// Wait for resolution. val, err := f.Await(ctx) if err != nil { return nil, err }
// Send release. _ = s.transport.Send(ctx, ReleaseMsg{ImportID: entry.ID, RefCount: entry.RefCount}) s.imports.Remove(entry.ID)
return val, nil}
// push sends a push message without pull. Returns the allocated import ID.// Used for promise pipelining where the result is consumed by a subsequent call.func (s *Session) push(ctx context.Context, tag string, targetID int64, method string, args []any) (int64, error) { expr, err := buildCallExpr(tag, targetID, method, args) if err != nil { return 0, err }
s.sendMu.Lock() entry := s.imports.Allocate() pushErr := s.transport.Send(ctx, PushMsg{Expr: expr}) s.sendMu.Unlock()
if pushErr != nil { return 0, fmt.Errorf("capnweb: send push: %w", pushErr) } return entry.ID, nil}
// Abort sends an abort message and terminates the session.func (s *Session) Abort(reason error) error { expr, _ := EncodeExpr(errorToExpr(reason)) s.ctxMu.RLock() ctx := s.ctx cancel := s.cancel s.ctxMu.RUnlock() err := s.transport.Send(ctx, AbortMsg{Expr: expr}) s.terminateAll(reason) cancel() return err}
// Close gracefully shuts down the session.func (s *Session) Close() error { s.terminateAll(fmt.Errorf("capnweb: session closed")) s.ctxMu.RLock() cancel := s.cancel s.ctxMu.RUnlock() cancel() return s.transport.Close()}
func (s *Session) getCtx() context.Context { s.ctxMu.RLock() defer s.ctxMu.RUnlock() return s.ctx}
// Done returns a channel that is closed when the session ends.func (s *Session) Done() <-chan struct{} { return s.done}
// Err returns the terminal error, if any.func (s *Session) Err() error { s.mu.Lock() defer s.mu.Unlock() return s.err}
// --- message handling ---
func (s *Session) handleMessage(msg Message) error { switch m := msg.(type) { case PushMsg: return s.handlePush(m) case PullMsg: return s.handlePull(m) case ResolveMsg: return s.handleResolve(m) case RejectMsg: return s.handleReject(m) case ReleaseMsg: return s.handleRelease(m) case StreamMsg: return s.handleStream(m) case PipeMsg: return s.handlePipe(m) case AbortMsg: return s.handleAbort(m) default: return fmt.Errorf("capnweb: unknown message type %T", msg) }}
func (s *Session) handlePush(m PushMsg) error { exportID := s.nextRemoteImportID() dr := &deferredResult{future: NewFuture()} s.exports.ExportWithID(exportID, dr)
s.wg.Add(1) go func() { defer s.wg.Done() result, err := s.evaluateAndCall(m.Expr) if err != nil { dr.future.Reject(err) } else { dr.future.Resolve(result) } }() return nil}
func (s *Session) handlePull(m PullMsg) error { exportID := m.ImportID
e := s.exports.Get(exportID) if e == nil { return nil } if dr, ok := e.Target.(*deferredResult); ok { s.wg.Add(1) go func() { defer s.wg.Done() val, err := dr.future.Await(s.getCtx()) _ = s.sendResult(exportID, val, err) }() } return nil}
func (s *Session) handleResolve(m ResolveMsg) error { s.mu.Lock() pc, ok := s.pending[m.ExportID] s.mu.Unlock() if !ok { return nil }
expr, err := DecodeExpr(m.Expr) if err != nil { pc.future.Reject(fmt.Errorf("capnweb: decode resolve: %w", err)) return nil } pc.future.Resolve(s.exprToValue(expr)) return nil}
func (s *Session) handleReject(m RejectMsg) error { s.mu.Lock() pc, ok := s.pending[m.ExportID] s.mu.Unlock() if !ok { return nil }
expr, err := DecodeExpr(m.Expr) if err != nil { pc.future.Reject(fmt.Errorf("capnweb: decode reject: %w", err)) return nil } if errExpr, ok := expr.(ErrorExpr); ok { pc.future.Reject(&errExpr) } else { pc.future.Reject(fmt.Errorf("capnweb: rejected: %v", s.exprToValue(expr))) } return nil}
func (s *Session) handleRelease(m ReleaseMsg) error { s.exports.HandleRelease(m.ImportID, m.RefCount) return nil}
func (s *Session) handlePipe(_ PipeMsg) error { exportID := s.nextRemoteImportID() p := newPipe() s.exports.ExportWithID(exportID, p) return nil}
// CreatePipe sends a ["pipe"] message to the remote, creating a pipe.// Returns a StreamWriter for sending chunks and a ReadableExpr that can// be passed as a method argument so the remote can read from the pipe.func (s *Session) CreatePipe(ctx context.Context) (*StreamWriter, Expr, error) { s.sendMu.Lock() entry := s.imports.Allocate() pipeErr := s.transport.Send(ctx, PipeMsg{}) s.sendMu.Unlock()
if pipeErr != nil { return nil, nil, fmt.Errorf("capnweb: send pipe: %w", pipeErr) }
writer := &StreamWriter{session: s, importID: entry.ID} readable := ReadableExpr{ImportID: entry.ID} return writer, readable, nil}
func (s *Session) handleStream(m StreamMsg) error { exportID := s.nextRemoteImportID() result, err := s.evaluateAndCall(m.Expr) return s.sendResult(exportID, result, err)}
func (s *Session) handleAbort(m AbortMsg) error { expr, err := DecodeExpr(m.Expr) if err != nil { return fmt.Errorf("capnweb: abort: %w", err) } if errExpr, ok := expr.(ErrorExpr); ok { return &errExpr } return fmt.Errorf("capnweb: remote abort: %v", s.exprToValue(expr))}
// --- internal helpers ---
func (s *Session) sendResult(exportID int64, val any, err error) error { if err != nil { encoded, _ := EncodeExpr(errorToExpr(err)) return s.transport.Send(s.getCtx(), RejectMsg{ExportID: exportID, Expr: encoded}) } expr, convErr := s.valueToExpr(val) if convErr != nil { encoded, _ := EncodeExpr(errorToExpr(convErr)) return s.transport.Send(s.getCtx(), RejectMsg{ExportID: exportID, Expr: encoded}) } encoded, encErr := EncodeExpr(expr) if encErr != nil { encoded, _ = EncodeExpr(errorToExpr(encErr)) return s.transport.Send(s.getCtx(), RejectMsg{ExportID: exportID, Expr: encoded}) } return s.transport.Send(s.getCtx(), ResolveMsg{ExportID: exportID, Expr: encoded})}
// errorToExpr converts a Go error to an ErrorExpr. If the error is already// an *ErrorExpr (via errors.As), the type and stack are preserved. Otherwise// it is wrapped as a generic "Error".func errorToExpr(err error) ErrorExpr { var errExpr *ErrorExpr if errors.As(err, &errExpr) { return *errExpr } return ErrorExpr{Type: "Error", Message: err.Error()}}
// Release sends a release message for the given import ID and removes it// from the import table. Used when the caller is done with a remote object// obtained via pass-by-reference.func (s *Session) Release(ctx context.Context, importID, refCount int64) error { err := s.transport.Send(ctx, ReleaseMsg{ImportID: importID, RefCount: refCount}) s.imports.Remove(importID) return err}
func (s *Session) evaluateAndCall(raw json.RawMessage) (any, error) { expr, err := DecodeExpr(raw) if err != nil { return nil, fmt.Errorf("capnweb: decode: %w", err) } switch e := expr.(type) { case ImportExpr: return s.dispatchCall(e.ImportID, e.Path, e.Args) case PipelineExpr: return s.dispatchCall(e.ImportID, e.Path, e.Args) case RemapExpr: return s.evaluateRemap(&e) default: return s.exprToValue(expr), nil }}
func (s *Session) dispatchCall(exportID int64, path []string, args []Expr) (any, error) { entry := s.exports.Get(exportID) if entry == nil { return nil, fmt.Errorf("capnweb: unknown export ID %d", exportID) }
target := entry.Target // Unwrap deferred results from prior pipeline stages. if dr, ok := target.(*deferredResult); ok { val, err := dr.future.Await(s.getCtx()) if err != nil { return nil, err } target = val } if len(path) == 0 { return target, nil }
methodName := path[len(path)-1] v := reflect.ValueOf(target) m := v.MethodByName(methodName) if !m.IsValid() { m = v.MethodByName(capitalize(methodName)) } if !m.IsValid() { return nil, NewTypeError(fmt.Sprintf("method %q not found on %T", methodName, target)) }
mt := m.Type() callArgs := make([]reflect.Value, 0, mt.NumIn())
paramIdx := 0 if mt.NumIn() > 0 && mt.In(0).Implements(reflect.TypeFor[context.Context]()) { callArgs = append(callArgs, reflect.ValueOf(s.getCtx())) paramIdx = 1 }
if args == nil { args = []Expr{} } for i, arg := range args { goVal := s.exprToValue(arg) idx := paramIdx + i switch { case idx < mt.NumIn(): callArgs = append(callArgs, coerceArg(goVal, mt.In(idx))) case mt.IsVariadic(): callArgs = append(callArgs, coerceArg(goVal, mt.In(mt.NumIn()-1).Elem())) default: callArgs = append(callArgs, reflect.ValueOf(goVal)) } }
results := m.Call(callArgs) return interpretResults(results)}
// valueToExpr converts a Go value to an Expr for wire encoding.// RpcTarget values are exported as ["export", id]; plain values are// wrapped as LiteralExpr.func (s *Session) valueToExpr(val any) (Expr, error) { if val == nil { return LiteralExpr{Value: nil}, nil } if _, ok := val.(RpcTarget); ok { entry := s.exports.Export(val) return ExportExpr{ExportID: entry.ID}, nil } rv := reflect.ValueOf(val) if rv.Kind() == reflect.Slice { hasRef := false for i := range rv.Len() { if _, ok := rv.Index(i).Interface().(RpcTarget); ok { hasRef = true break } } if hasRef { elems := make([]Expr, rv.Len()) for i := range rv.Len() { e, err := s.valueToExpr(rv.Index(i).Interface()) if err != nil { return nil, err } elems[i] = e } return ArrayExpr{Elements: elems}, nil } } return LiteralExpr{Value: val}, nil}
func (s *Session) exprToValue(e Expr) any { switch v := e.(type) { case LiteralExpr: return v.Value case UndefinedExpr: return nil case InfExpr: return math.Inf(1) case NegInfExpr: return math.Inf(-1) case NaNExpr: return math.NaN() case BytesExpr: return v.Data case BigIntExpr: return v.Value case DateExpr: return v.Time case ErrorExpr: return &v case HeadersExpr: return v.Header case ExportExpr: entry := s.imports.Insert(v.ExportID) return entry case ReadableExpr: entry := s.exports.Get(v.ImportID) if entry == nil { return nil } if p, ok := entry.Target.(*pipe); ok { return &StreamReader{pipe: p} } return nil case WritableExpr: return &StreamWriter{session: s, importID: v.ExportID} case ArrayExpr: out := make([]any, len(v.Elements)) for i, el := range v.Elements { out[i] = s.exprToValue(el) } return out default: return nil }}
func (s *Session) terminateAll(err error) { s.mu.Lock() defer s.mu.Unlock() s.err = err for _, pc := range s.pending { pc.future.Reject(err) }}
func (s *Session) nextRemoteImportID() int64 { s.mu.Lock() defer s.mu.Unlock() s.remoteImportID++ return s.remoteImportID}
// evaluateRemap evaluates a remap expression — server-side .map() over a// collection. Uses a scoped import table where negative IDs reference// captures, 0 is the current element, and positive IDs are previous// instruction results.func (s *Session) evaluateRemap(r *RemapExpr) (any, error) { // Resolve the collection. collection, err := s.dispatchCall(r.ImportID, r.Path, nil) if err != nil { return nil, err }
items, ok := collection.([]any) if !ok { return nil, NewTypeError(fmt.Sprintf("remap: expected array, got %T", collection)) }
// Resolve captures. captures := make([]any, len(r.Captures)) for i, cap := range r.Captures { captures[i] = s.exprToValue(cap) }
// Map over elements. results := make([]any, len(items)) for i, element := range items { val, err := s.evaluateRemapElement(element, captures, r.Instructions) if err != nil { return nil, fmt.Errorf("remap element %d: %w", i, err) } results[i] = val } return results, nil}
func (s *Session) evaluateRemapElement(element any, captures []any, instructions []Expr) (any, error) { // Internal import table: negative → captures, 0 → element, positive → results instrResults := make([]any, 0, len(instructions))
for _, instr := range instructions { val, err := s.evaluateRemapInstr(instr, element, captures, instrResults) if err != nil { return nil, err } instrResults = append(instrResults, val) }
if len(instrResults) == 0 { return element, nil } return instrResults[len(instrResults)-1], nil}
func (s *Session) evaluateRemapInstr(instr Expr, element any, captures, results []any) (any, error) { switch e := instr.(type) { case ImportExpr: target := s.remapResolveID(e.ImportID, element, captures, results) return s.remapEvalRef(target, e.Path, e.Args, element, captures, results) case PipelineExpr: target := s.remapResolveID(e.ImportID, element, captures, results) return s.remapEvalRef(target, e.Path, e.Args, element, captures, results) default: return s.exprToValue(instr), nil }}
func (s *Session) remapEvalRef(target any, path []string, args []Expr, element any, captures, results []any) (any, error) { if len(path) == 0 && args == nil { return target, nil } if len(path) > 0 && args == nil { return accessPath(target, path), nil } resolvedArgs := make([]Expr, len(args)) for i, arg := range args { val, err := s.evaluateRemapInstr(arg, element, captures, results) if err != nil { return nil, err } resolvedArgs[i] = LiteralExpr{Value: val} } return s.dispatchCallOnValue(target, path, resolvedArgs)}
func (s *Session) remapResolveID(id int64, element any, captures, results []any) any { switch { case id == 0: return element case id < 0: idx := int(-id - 1) if idx < len(captures) { return captures[idx] } return nil default: idx := int(id - 1) if idx < len(results) { return results[idx] } return nil }}
func accessPath(val any, path []string) any { for _, key := range path { m, ok := val.(map[string]any) if !ok { return nil } val = m[key] } return val}
// dispatchCallOnValue calls a method on a Go value directly (without export// table lookup). Used by remap to call methods on resolved capture values.func (s *Session) dispatchCallOnValue(target any, path []string, args []Expr) (any, error) { if target == nil { return nil, NewTypeError("remap: nil target") }
// If target is an ImportEntry (from a capture), look up the export. if entry, ok := target.(*ImportEntry); ok { return s.dispatchCall(entry.ID, path, args) }
// If target is an ExportEntry, use its target. if entry, ok := target.(*ExportEntry); ok { target = entry.Target }
if len(path) == 0 { return target, nil }
methodName := path[len(path)-1] v := reflect.ValueOf(target) m := v.MethodByName(methodName) if !m.IsValid() { m = v.MethodByName(capitalize(methodName)) } if !m.IsValid() { return nil, NewTypeError(fmt.Sprintf("remap: method %q not found on %T", methodName, target)) }
mt := m.Type() callArgs := make([]reflect.Value, 0, mt.NumIn())
paramIdx := 0 if mt.NumIn() > 0 && mt.In(0).Implements(reflect.TypeFor[context.Context]()) { callArgs = append(callArgs, reflect.ValueOf(s.getCtx())) paramIdx = 1 }
for i, arg := range args { goVal := s.exprToValue(arg) idx := paramIdx + i if idx < mt.NumIn() { callArgs = append(callArgs, coerceArg(goVal, mt.In(idx))) } else { callArgs = append(callArgs, reflect.ValueOf(goVal)) } }
results := m.Call(callArgs) return interpretResults(results)}
type deferredResult struct { future *Future}
func buildCallExpr(tag string, targetID int64, method string, args []any) (json.RawMessage, error) { if method != "" { encodedArgs, err := encodeArgs(args) if err != nil { return nil, err } return json.Marshal([]any{tag, targetID, []string{method}, encodedArgs}) } return json.Marshal([]any{tag, targetID})}
// encodeArgs encodes call arguments. Expr values are encoded via EncodeExpr;// plain values are encoded via json.Marshal.func encodeArgs(args []any) ([]json.RawMessage, error) { if len(args) == 0 { return []json.RawMessage{}, nil } out := make([]json.RawMessage, len(args)) for i, arg := range args { if expr, ok := arg.(Expr); ok { encoded, err := EncodeExpr(expr) if err != nil { return nil, err } out[i] = encoded } else { encoded, err := json.Marshal(arg) if err != nil { return nil, err } out[i] = encoded } } return out, nil}
func capitalize(s string) string { if s == "" { return s } return string(s[0]-32) + s[1:]}
func coerceArg(val any, target reflect.Type) reflect.Value { if val == nil { return reflect.Zero(target) } v := reflect.ValueOf(val) if v.Type().AssignableTo(target) { return v } if v.Type().ConvertibleTo(target) { return v.Convert(target) } return v}
func interpretResults(results []reflect.Value) (any, error) { switch len(results) { case 0: return nil, nil case 1: v := results[0] if v.Type().Implements(reflect.TypeFor[error]()) { if v.IsNil() { return nil, nil } return nil, v.Interface().(error) } return v.Interface(), nil default: last := results[len(results)-1] if last.Type().Implements(reflect.TypeFor[error]()) { var err error if !last.IsNil() { err = last.Interface().(error) } if len(results) == 2 { return results[0].Interface(), err } vals := make([]any, len(results)-1) for i := range len(results) - 1 { vals[i] = results[i].Interface() } return vals, err } vals := make([]any, len(results)) for i, r := range results { vals[i] = r.Interface() } return vals, nil }}