goja

type BaseConfig ¶

type BaseConfig struct {
	// Name identifies the subsystem ("captable", "esign", "dataroom"). It names
	// the goja host AND the per-tenant database it opens.
	Name string
	// Bundle is the self-contained goja bundle exposing globalThis.handle.
	Bundle []byte
	// Schema is the per-tenant SQLite DDL, run (idempotently — use
	// CREATE TABLE IF NOT EXISTS) on every tenant DB when it first opens.
	Schema string
	// DataDir is the deployment data root; per-tenant files land where namespace
	// renders them, at {DataDir}/orgs/{slug}/{Name}.db.
	DataDir string
	// OnOpen is an optional per-tenant seed hook run ONCE after migration (e.g.
	// captable seeds the tenant's company row). It runs outside the per-request
	// transaction. May be nil.
	OnOpen func(ctx context.Context, tenant string, db *sql.DB) error
	// HostFns are OPTIONAL extra native host globals injected onto the runtime on
	// every Dispatch, ALONGSIDE __db/__newId/__now — for capabilities goja cannot
	// provide that a subsystem implements in Go (e.g. esign injects __pdf =
	// { stamp, sign } for PDF rendering + x509/PKCS#7 signing). Values are Go
	// funcs or map[string]any of Go funcs (goja exposes them as callable JS). They
	// are process-global (set once at NewBase), not per-tenant; the binding stays
	// domain-free. May be nil. A key MUST NOT collide with __db/__newId/__now/__blob.
	HostFns map[string]any
	// Blob is the OPTIONAL object-storage seam (see BlobStore). When set, the binding
	// injects globalThis.__blob = { put(key, b64), get(key) -> b64 } on every
	// Dispatch, bound to the tenant: keys are prefixed with {Name}/{TenantSegment}
	// so a bundle can NEVER address another tenant's blob. Payloads cross as base64
	// strings (goja-friendly); the binding decodes/encodes at the boundary so the
	// bundle never handles raw bytes. nil ⇒ no __blob is injected. This is the ONE
	// way a bundle keeps big binaries out of its per-tenant SQLite.
	Blob BlobStore
}

BaseConfig configures a BaseHost.

type BaseHost ¶

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

BaseHost is a compiled bundle + its per-tenant Base stores. Safe for concurrent use.

func NewBase(cfg BaseConfig) (*BaseHost, error)

func (h *BaseHost) Close() error

func (h *BaseHost) Dispatch(ctx context.Context, tenant string, req BaseRequest) (*Response, error)

type BaseRequest ¶

type BaseRequest struct {
	Route  string
	Params map[string]string
	Query  map[string]string
	Body   any
}

BaseRequest is the dispatch envelope. The binding adds the tenant (as orgId) and the Base bridge; the caller supplies route/params/query/body.

type BlobStore ¶

type BlobStore interface {
	Put(ctx context.Context, key string, payload []byte) error
	Get(ctx context.Context, key string) ([]byte, error)
}

BlobStore is the ONE object-storage seam a bundle uses to persist large binary payloads OUTSIDE its per-tenant SQLite (e.g. sign's PDFs — a 32 MiB base64 blob in a TEXT column would bloat the tenant DB and get copied on every read). The cloud VFS/S3 data plane (deps.VFS) satisfies it, exactly as clients/dataroom already uses it for document bytes. Keys are opaque; the binding tenant-scopes them.

type BodyField ¶ added in v1.801.433

type BodyField interface {
	// contains filtered or unexported methods
}

BodyField is one field of an assembled bundle body: a Scalar for a single token, a ScalarList for a lenient array. The interface is CLOSED — its method is unexported — so those two are the whole vocabulary, and Body needs no default case for a kind that cannot exist.

type BundleErr ¶ added in v1.801.433

type BundleErr struct {
	// Status is the bundle's own HTTP status.
	Status int
	// Body is the bundle's own response bytes, written back verbatim.
	Body []byte
	// Msg is the human sentence for a caller that is not on the HTTP path.
	Msg string
}

BundleErr is the bundle's OWN non-2xx answer, carried as a Go error so a typed op can return it. A bundle authors envelopes cloud has no vocabulary for, and zip's error path renders {status,code,error}, which has nowhere to put them. So the op returns the bundle's status and its BYTES, and Envelope writes them back untouched.

It is not an escape from typing. The op still declares its In and its Out, so the document, the MCP tool, the CLI command and the SDK method all exist.

func (e *BundleErr) Error() string

func (e *BundleErr) Unwrap() error

type Config ¶

type Config struct {
	// Name identifies the service for error messages ("plans", "pricing").
	Name string
	// Bundle is the goja bundle source (goja/bundle.js from the service repo).
	Bundle []byte
	// Globals are injected onto each runtime before the bundle runs, e.g.
	// {"__PLANS_DATA__": <catalog>}. Values are converted via goja.ToValue.
	// Pointers to the same Go value are shared read-only across runtimes; the
	// bundles never mutate injected globals.
	Globals map[string]any
}

Config configures a Host.

type Host ¶

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

Host is a compiled service bundle plus a pool of goja runtimes that have had the bundle + the injected globals evaluated. Safe for concurrent use.

func New(cfg Config) (*Host, error)

func (h *Host) Close() error

func (h *Host) Dispatch(ctx context.Context, req Request) (*Response, error)

func (h *Host) DispatchWith(ctx context.Context, req Request, hostGlobals map[string]any) (*Response, error)

func (h *Host) Eval(ctx context.Context, fnName string, jsonArg []byte) ([]byte, error)

func (h *Host) SetGlobal(key string, value any)

type Request ¶

type Request struct {
	Route  string            `json:"route"`
	Params map[string]string `json:"params,omitempty"`
	Query  map[string]string `json:"query,omitempty"`
	Tenant string            `json:"tenant,omitempty"`

	// OrgID is the validated tenant for read-WRITE subsystems (captable). It is
	// passed to handle as req.orgId; the bundle uses it to scope every row.
	// Read-only bundles (plans/pricing) ignore it and read Tenant instead.
	OrgID string `json:"orgId,omitempty"`
	// Body is the decoded request body for mutations, passed to handle as
	// req.body. nil for reads. Whatever json.Unmarshal produced (map/slice/scalar)
	// is converted to a JS value by goja.
	Body any `json:"body,omitempty"`
}

Request is the dispatch envelope handed to globalThis.handle in JS.

type Response ¶

type Response struct {
	Status int             `json:"status"`
	Body   json.RawMessage `json:"body"`
}

Response is what globalThis.handle returns: an HTTP status + an opaque body that the host serializes straight to JSON.

type Scalar ¶ added in v1.801.433

type Scalar string

Scalar is ONE JSON value carried from the caller to the bundle unchanged — the token exactly as it arrived, quotes and all: `"Acme"`, `123`, `null`, and a composite token too, which is how a lenient array field is carried per element as []Scalar.

It exists because a bundle's validators are LENIENT in a way no Go type is. A helper that calls String(v) stores `{"taxId":12345}` as "12345" today, and a *string field would refuse it with a 400 — making the route accept LESS. A helper that REFUSES a non-string answers in the bundle's own envelope, which a Go field refusing it first would replace with zip's. Carrying the token verbatim keeps both: the bundle sees what the caller sent and stays the only judge of it.

A Go string is the carrier because it is a string KIND, so every projection describes the field as `string` — which is what these fields are. The leniency is not in the schema; it is named in each field's own prose.

The zero value means ABSENT — no key was on the wire — which is why a field of this type is `omitempty` and never a pointer. A pointer would collapse the distinction a partial update depends on: encoding/json sets a pointer field to nil for an explicit `null` WITHOUT calling UnmarshalJSON, so `{"city":null}` and `{}` would arrive identically. A non-pointer Scalar records `null` as the four bytes `null`, and an empty JSON string as the two bytes `""`, so neither can be confused with absent.

func (s Scalar) MarshalJSON() ([]byte, error)

func (s *Scalar) UnmarshalJSON(b []byte) error

type ScalarList ¶ added in v1.801.433

type ScalarList []Scalar

ScalarList is a lenient ARRAY field: each element is carried verbatim, so a bundle that reads the elements itself stays the only judge of them.

It exists because Scalar would describe an array field as a `string`, and a wrong type in the schema is worse here than in prose: the agent, the SDK and the CLI all read it, and a bundle that tests Array.isArray silently substitutes an EMPTY list for anything that is not an array. So a caller told `string` sends one, the bundle discards it, and the call succeeds having ignored the field. Declaring the array is what makes that failure impossible to reach.

Leniency survives anyway, in both directions. A non-array body value is a decode error that Fill drops, leaving the field nil — ABSENT, which is exactly the `undefined` the bundle turns into its own empty list. And an element that is not a string is carried as the token it was, so the bundle sees what the caller sent.

type SizedIn ¶ added in v1.801.433

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

SizedIn is the request-size half of an input, embedded by every body-carrying typed op.

The relay capped a body and answered 413 AFTER resolving the tenant. A typed op never sees the request, so the size is recorded where the bytes are — the input's own UnmarshalJSON — and read back after the tenant is resolved, which is what keeps a 403 ahead of a 413 for the caller that has both problems.

The field is unexported, so it reaches no schema: zip's projector walks an untagged embedded struct and keeps only its EXPORTED fields, so embedding this adds nothing a caller could send.

func (s *SizedIn) Fill(max int, b []byte, v any)

func (s SizedIn) Oversize() bool