application

Documentation

Overview

Package application stages and atomically publishes complete executable generations. Runtime, HTTP, MCP and type authority share one publication.

Index

• Variables
• type AsyncConfig
• type Build
• type Manager
  • func New(types *typecatalog.Catalog, configure ...Option) (*Manager, error)
  • func (m *Manager) DispatchStorageEvent(ctx context.Context, object storage.Object) error
  • func (m *Manager) ExportOpenAPI(ctx context.Context, request openapi.ExportRequest) ([]byte, error)
  • func (m *Manager) HandleJob(ctx context.Context, event *jobs.Event) (any, error)
  • func (m *Manager) InvokeComponent(ctx context.Context, request exec.ComponentRequest) (any, error)
  • func (m *Manager) JobStatus(ctx context.Context, id string) (*xasync.Job, error)
  • func (m *Manager) Metadata(ctx context.Context) (*Metadata, error)
  • func (m *Manager) Pin(ctx context.Context) (context.Context, mcpserver.ServerService, error)
  • func (m *Manager) PinOwned(ctx context.Context) (context.Context, mcpserver.ServerService, error)
  • func (m *Manager) PinSnapshot(ctx context.Context) (context.Context, mcpserver.ServerService, error)
  • func (m *Manager) Reload(ctx context.Context, request Request) error
  • func (m *Manager) RepublishJob(ctx context.Context, id string) error
  • func (m *Manager) Revision() uint64
  • func (m *Manager) ScheduleJob(ctx context.Context, request jobs.Submission) (*jobs.Scheduled, error)
  • func (m *Manager) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (m *Manager) Shutdown(ctx context.Context) error
  • func (m *Manager) Types(ctx context.Context) (*typecatalog.Catalog, error)
• type Metadata
• type Option
  • func WithAsync(config AsyncConfig) Option
  • func WithObservability(config runtime.ObservabilityConfig) Option
• type Request

Variables

var ErrClosed = errors.New("application is shut down")

var ErrStale = errors.New("application generation is stale")

Types

type AsyncConfig

type AsyncConfig struct {
	Store        *jobs.SQLStore
	Authorize    jobs.Authorizer
	TTL          time.Duration
	ErrorTTL     time.Duration
	Notify       func(context.Context, *xasync.Job) error
	FS           afs.Service
	Notification xasync.Notification
	// Empty JobURL disables polling, while schedule/status/external dispatch stay
	// available. Notification.Destination independently selects publication.
	Watch jobstorage.WatchConfig
}

AsyncConfig selects existing job and AFS services. Resolve Store once with bootstrap.JobStoreConfig.NewStore before New; its connector/table selection is fixed across reloads. The application never closes the caller-owned database. Callbacks and FS must be safe for concurrent use and remain valid until Shutdown completes. Authorize is mandatory; there is no implicit principal or policy.

type Build

type Build struct {
	Documentation xdocs.Source
	Components    []*registry.RegisteredComponent
	// Observability is application-owned; configure it through application.New.
	// Stage-local observation options are rejected before constructing a runtime.
	RuntimeOptions []runtime.Option
	MCP            mcp.Config
	// HTTP is validated with the rest of the stage before publication. Manager
	// supplies its shared server lifetime; stages must not supply Warmup.Lifetime.
	HTTP   gateway.Config
	Logger xlogger.Logger
	// BootstrapLogger emits source/index lifecycle diagnostics without enabling
	// request logging for protocol handlers.
	BootstrapLogger xlogger.Logger
	Version         string
	// Resources is the stage-owned filesystem authority shared by all compilers,
	// runtime binding and MCP. Conflicting explicitly configured stores fail.
	Resources *resource.Store
	// Types is the actual staged catalog consumed by component compilation when
	// that compiler creates its own detached catalog. Nil uses Compile's input.
	Types *typecatalog.Catalog
	// Index publishes bootstrap route/MCP metadata without compiling every
	// component. Materializer is invoked once per used component and generation.
	Index        *bootstrapindex.Snapshot
	Materializer bootstrapindex.Materializer
	// Preload names only explicitly configured startup consumers such as cache
	// warmup or async routes; unrelated indexed components remain lazy.
	Preload []spec.Key
	// Shutdown owns stage-local external resources such as database handles.
	// After publication, Manager calls it exactly once when the generation has
	// retired and all admitted requests have released their generation lease. A
	// failed stage is also shut down before Reload returns.
	Shutdown func(context.Context) error
}

Build is the complete result of trusted stage composition. Components must be newly compiled; shared dependencies and providers must be immutable. Successful publication transfers ownership: callers must not mutate the returned carriers. MCP.Components and Invoker are owned by publication and must be left empty.

type Manager

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

func New

func New(types *typecatalog.Catalog, configure ...Option) (*Manager, error)

New snapshots the base package type authority used by every staged source set. Types authored by reloadable DQL belong in Request.Compile, not this seed.

func (*Manager) DispatchStorageEvent

func (m *Manager) DispatchStorageEvent(ctx context.Context, object storage.Object) error

DispatchStorageEvent owns admission through download, authorization, execution and terminal write-back. External delivery adapters own event acknowledgement; the managed Watcher owns acknowledgement for polling deliveries.

func (*Manager) ExportOpenAPI

func (m *Manager) ExportOpenAPI(ctx context.Context, request openapi.ExportRequest) ([]byte, error)

ExportOpenAPI exports the pinned generation's public document. This is a trusted application API; network document-access policy belongs to HTTP.

func (*Manager) HandleJob

func (m *Manager) HandleJob(ctx context.Context, event *jobs.Event) (any, error)

HandleJob accepts original job event identity; the existing jobs service loads route/state authority from its durable row and reauthorizes replay.

func (*Manager) InvokeComponent

func (m *Manager) InvokeComponent(ctx context.Context, request exec.ComponentRequest) (any, error)

func (*Manager) JobStatus

func (m *Manager) JobStatus(ctx context.Context, id string) (*xasync.Job, error)

func (*Manager) Metadata

func (m *Manager) Metadata(ctx context.Context) (*Metadata, error)

func (*Manager) Pin

func (m *Manager) Pin(ctx context.Context) (context.Context, mcpserver.ServerService, error)

Pin implements MCP's request snapshot source. It never loads a second generation when an outer HTTP or application invocation already pinned one.

func (*Manager) PinOwned

func (m *Manager) PinOwned(ctx context.Context) (context.Context, mcpserver.ServerService, error)

PinOwned is used by the MCP transport, which releases the generation after completing one protocol operation.

func (*Manager) PinSnapshot

func (m *Manager) PinSnapshot(ctx context.Context) (context.Context, mcpserver.ServerService, error)

PinSnapshot supplies MCP request routing without creating a caller-retained public pin; the protocol handler acquires and releases operation ownership.

func (*Manager) Reload

func (m *Manager) Reload(ctx context.Context, request Request) error

Reload stages off to the side and publishes once. Concurrent superseded stages fail rather than overwriting a newer source generation.

func (*Manager) RepublishJob

func (m *Manager) RepublishJob(ctx context.Context, id string) error

func (*Manager) Revision

func (m *Manager) Revision() uint64

func (*Manager) ScheduleJob

func (m *Manager) ScheduleJob(ctx context.Context, request jobs.Submission) (*jobs.Scheduled, error)

ScheduleJob captures against the generation current at admission. A durable pending row is replayed against metadata current at dispatch, even after reload. An operation already admitted finishes with its one pinned service.

func (*Manager) ServeHTTP

func (m *Manager) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Manager) Shutdown

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown closes publication and admission, cancels and joins accepted async work and HTTP warmups across generations. A caller deadline bounds waiting, not cleanup: later calls join the same completion. Protocol servers still own transport shutdown and ordinary requests.

func (*Manager) Types

func (m *Manager) Types(ctx context.Context) (*typecatalog.Catalog, error)

Types returns a detached view of the currently published type authority.

type Metadata

type Metadata struct {
	Revision   uint64            `json:"revision"`
	Components []*spec.Component `json:"components"`
}

type Option

type Option func(*options) error

Option configures application-owned services shared by managed generations.

func WithAsync

func WithAsync(config AsyncConfig) Option

WithAsync installs durable job services and starts the configured watcher on the first successful Reload. Configuration is fixed for this Manager lifetime.

func WithObservability

func WithObservability(config runtime.ObservabilityConfig) Option

WithObservability configures one capture/export owner for this Manager. It is stable across reloads and pinned generations, like the managed warmup lifetime.

type Request

type Request struct {
	// Revision is the monotonic revision of the complete authored source set.
	Revision uint64
	// Compile receives a detached catalog. It must compile the complete source
	// set and all plans before returning, without side effects on active services.
	Compile func(context.Context, *typecatalog.Catalog) (*Build, error)
}