server

Documentation

Overview

Package server exposes a engine.Runtime over HTTP: a page to view the notebook, a Server-Sent Events stream of cell updates, and an endpoint to post leaf edits.

This package is the transport, and it is the ONLY place net/http appears. The engine emits Events on a channel and knows nothing about HTTP; the server subscribes and pushes. That separation is what keeps headless, WASM, and batch modes free — none of them link this package.

The client is deliberately ignorant of Go types: it receives {cell, mime, data} blobs and renders them, and posts {leaf, value} edits back. Renderers run in Go, in-process.

Index

• func Serve(ctx context.Context, addr string, rt *engine.Runtime, meta []engine.CellMeta, ...) error
• func ServeNotebook(ctx context.Context, addr string, rt *engine.Runtime, meta []engine.CellMeta, ...) error
• func ServeNotebookReady(ctx context.Context, addr string, rt *engine.Runtime, meta []engine.CellMeta, ...) error
• type Server
  • func New(rt *engine.Runtime, meta []engine.CellMeta, set SetFunc) *Server
  • func NewNotebook(rt *engine.Runtime, meta []engine.CellMeta, prov engine.Provenance, ...) *Server
  • func (s *Server) Handler() http.Handler
• type SetFunc

Functions

func Serve

func Serve(ctx context.Context, addr string, rt *engine.Runtime, meta []engine.CellMeta, set SetFunc) error

Serve starts an HTTP server on addr and blocks. Each client that connects to the event stream triggers a full wave, so a freshly-opened page always shows current state without a separate startup wave here. It shows no provenance; use ServeNotebook to display build identity.

func ServeNotebook

func ServeNotebook(ctx context.Context, addr string, rt *engine.Runtime, meta []engine.CellMeta, prov engine.Provenance, set SetFunc) error

ServeNotebook is Serve plus build provenance, shown on the page so a served binary — e.g. one scp'd to a login node months ago — can say what it is. Serve delegates here with an empty Provenance, so the older signature is unchanged.

func ServeNotebookReady

func ServeNotebookReady(ctx context.Context, addr string, rt *engine.Runtime, meta []engine.CellMeta, prov engine.Provenance, layout [][]string, set SetFunc, onReady func(addr string)) error

ServeNotebookReady is ServeNotebook that binds the listener BEFORE serving and reports the resolved address through onReady, so a caller (or a launcher reading the process's stdout) learns the real port even when addr requested an OS-assigned one (host:0). This is the addressing half of the notebook-as-service seam (docs/notebook-as-service.md): the process picks its port — only it knows what is free on the box — but ANNOUNCES it rather than fixing it, so a parent never has to poll-and-hope. onReady is called once, with the bound host:port, just before the accept loop starts; a nil onReady preserves the old behavior.

Types

type Server

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

Server serves a runtime over HTTP.

func New

func New(rt *engine.Runtime, meta []engine.CellMeta, set SetFunc) *Server

New builds a server for a runtime, its cell metadata, and a type-aware leaf setter. If set is nil, edits write the raw JSON value directly (fine for tests whose leaves are already the right type). It carries no provenance; use NewNotebook to display build identity.

func NewNotebook

func NewNotebook(rt *engine.Runtime, meta []engine.CellMeta, prov engine.Provenance, set SetFunc) *Server

NewNotebook is New plus build provenance, shown on the page so a served binary can say what it is. New delegates here with an empty Provenance, so the older signature keeps working unchanged.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the HTTP handler, so callers can wrap or test it without a live listener.

type SetFunc

type SetFunc func(ctx context.Context, leaf string, raw any)

SetFunc applies a leaf edit: it coerces the raw JSON value (numbers arrive as float64) into the leaf's static Go type and writes it through the head, then runs the wave. The generated main supplies this because only codegen knows each leaf's real type — the server itself is type-agnostic. A nil SetFunc falls back to writing the raw value (used in tests with already-typed values).