server

type ChannelStream ¶

type ChannelStream struct {
	Ch      <-chan any
	OnClose func()
	// contains filtered or unexported fields
}

ChannelStream adapts a channel of frames to the Stream interface. Closing the underlying channel (or canceling the context) ends the stream; transports always call Close, so it's safe to wire a cleanup goroutine there.

func (s *ChannelStream) Close() error

func (s *ChannelStream) Next(ctx context.Context) (any, bool, error)

type Handler ¶

type Handler func(req *Request) Response

Handler is the signature every peng operation implements. Handlers are pure functions of their Request; they don't know which transport invoked them.

type MCPMeta ¶

type MCPMeta struct {
	Name    string // tool name as exposed to MCP clients
	Confirm bool   // require confirm:true argument before invocation
}

MCPMeta marks a route for inclusion in the MCP tool list.

type Mux ¶

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

Mux maps (method, path) tuples to handlers. Routes are matched in registration order, so register specific routes ("/migrations/up") before parameterized ones ("/migrations/{version}").

func NewMux() *Mux

func (m *Mux) Dispatch(ctx context.Context, method, path string,
	query url.Values, headers map[string]string, body json.RawMessage) Response

func (m *Mux) Handle(method, pattern string, h Handler, opts ...RouteOption)

func (m *Mux) Routes() []*Route

type Request ¶

type Request struct {
	Ctx     context.Context
	Method  string
	Path    string
	Params  map[string]string
	Query   url.Values
	Headers map[string]string
	Body    json.RawMessage
}

Request is the transport-agnostic input to every handler.

Body is left as raw JSON so each handler decodes into its own argument type — keeps the mux free of generics. Params holds path-pattern captures (e.g. for "/migrations/{version}", Params["version"] is the matched segment). Headers carries only transport-relevant entries (Authorization, Idempotency-Key) — bulk request metadata stays out.

type Response ¶

type Response struct {
	Status  int
	Headers map[string]string
	Body    any
	Stream  Stream
}

Response is the transport-agnostic output of every handler.

Exactly one of Body or Stream should be set. Status without either signals a no-body response (typically 204). Headers are optional; transports may ignore them (MCP, for instance, has no header concept).

func JSON(status int, body any) Response

func NoContent() Response

func Problem(status int, title, detail string) Response

func Streaming(s Stream) Response

type Route ¶

type Route struct {
	Method  string
	Pattern string
	Handler Handler
	MCP     *MCPMeta
	Stream  bool
	Summary string
	OpID    string // matches operationId in docs/openapi-WIP.yaml
	// contains filtered or unexported fields
}

Route is the registered handler entry. Exported so transport adapters can iterate routes (e.g. the MCP adapter builds its tool list this way).

type RouteOption ¶

type RouteOption func(*Route)

RouteOption configures a route at registration time.

func WithMCP(name string, confirm bool) RouteOption

func WithOpID(id string) RouteOption

func WithStreaming() RouteOption

func WithSummary(s string) RouteOption

type Stream ¶

type Stream interface {
	Next(ctx context.Context) (frame any, done bool, err error)
	Close() error
}

Stream is a unidirectional producer of JSON-encodable frames. The transport drives [Next] until done is true or ctx is canceled. HTTP formats each frame as an SSE event; IPC wraps each as a "chunk" envelope on the same channel as request/response; MCP refuses to register streaming routes.