runtime

package
v0.3.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2026 License: Apache-2.0 Imports: 69 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AssistantTokenKeyEnv     = "SCENERY_ASSISTANT_TOKEN_KEY"
	AssistantTokenKeyFileEnv = "SCENERY_ASSISTANT_TOKEN_KEY_FILE"
)

AssistantTokenKeyEnv and AssistantTokenKeyFileEnv are the server-only stable sealing-key handoff used by generated assistant registrations. The file variant is the preferred local-development path; production may use either an existing secret environment or a mode-0600 file.

View Source 
const (
	ContractCLIRequestKind            = "scenery.contract-cli.request"
	ContractCLIResponseKind           = "scenery.contract-cli.response"
	ContractCLIRequestSchemaRevision  = "sha256:95f956252d5b0a53ba551fb8c7f33ad7a928b1a3f6d858e94f0d39de69e470b1"
	ContractCLIResponseSchemaRevision = "sha256:42b3bc64a69833b0456dfaf6d4332fcad6a4eb208fed48b4723f17b1d3360198"
)
View Source 
const (
	ContractSourcePath     = "path"
	ContractSourcePathTail = "path_tail"
	ContractSourceQuery    = "query"
	ContractSourceHeader   = "header"
	ContractSourceCookie   = "cookie"
)
View Source 
const (
	Public  = runtimeapi.Public
	Auth    = runtimeapi.Auth
	Private = runtimeapi.Private
)
View Source 
const (
	ParamString = runtimeapi.ParamString
	ParamBool   = runtimeapi.ParamBool
	ParamInt    = runtimeapi.ParamInt
	ParamInt8   = runtimeapi.ParamInt8
	ParamInt16  = runtimeapi.ParamInt16
	ParamInt32  = runtimeapi.ParamInt32
	ParamInt64  = runtimeapi.ParamInt64
	ParamUint   = runtimeapi.ParamUint
	ParamUint8  = runtimeapi.ParamUint8
	ParamUint16 = runtimeapi.ParamUint16
	ParamUint32 = runtimeapi.ParamUint32
	ParamUint64 = runtimeapi.ParamUint64
)
View Source 
const AssistantRuntimeConfigEnv = "SCENERY_ASSISTANT_RUNTIME_CONFIG"

AssistantRuntimeConfigEnv is the one runtime configuration seam used by a generated app for helper descriptors. Its value is a path to a provider-neutral JSON file written by the supervisor or production launcher. Keeping one file for all assistants avoids a singular ambient address/token environment variable and makes multi-assistant startup deterministic.

View Source 
const ContractRuntimeABI = "scenery.go-runtime/v1"
View Source 
const (
	// MCPToolMaxBytes is the framework ceiling for one generated MCP tool
	// request or result. Individual registrations may choose a lower limit.
	MCPToolMaxBytes int64 = mcpcontract.MaximumInputBytes
)

Variables

View Source 
var (
	// ErrMCPFederationNotFound is returned by readiness helpers when a server
	// has not been registered or has not finished initialization.
	ErrMCPFederationNotFound = errors.New("MCP federation is not registered")
	// ErrMCPFederationNotReady is a provider-neutral readiness result. The
	// detailed remote error and credentials are intentionally not retained.
	ErrMCPFederationNotReady = errors.New("MCP federation is not ready")
)

Functions

func AddContractResponseCookie added in v0.3.2 

func AddContractResponseCookie(response *ContractHTTPResponse, specification ContractResponseCookie, value any, configured ...ContractResponseValueOptions) error

func AddContractResponseHeader added in v0.3.2 

func AddContractResponseHeader(response *ContractHTTPResponse, name string, value any, configured ...ContractResponseValueOptions) error

func ContractCLIInvalidInput added in v0.3.2 

func ContractCLIInvalidInput(err error) error

func ContractDurableFailureOutcome added in v0.3.2 

func ContractDurableFailureOutcome(err error) string

func ContractProviderABIs added in v0.3.2 

func ContractProviderABIs() map[string]string

ContractProviderABIs returns an immutable snapshot of loaded provider runtime attestations for the application registration boundary.

func ContractSystemError added in v0.3.2 

func ContractSystemError(err error) error

func CurrentRequest 

func CurrentRequest() *shared.Request

func DecodeContractInput added in v0.3.2 

func DecodeContractInput[T any](request *http.Request, pathValues map[string]string, schema ContractRequestSchema) (T, error)

func DecodeContractJSON added in v0.3.2 

func DecodeContractJSON[T any](request *http.Request) (T, error)

func DispatchAndWaitContractDurableExecutionWithOptions added in v0.3.2 

func DispatchAndWaitContractDurableExecutionWithOptions(ctx context.Context, address string, input any, options ContractDurableDispatchOptions) ([]byte, error)

func DispatchContractDurableExecutionWithOptions added in v0.3.2 

func DispatchContractDurableExecutionWithOptions(ctx context.Context, address string, input any, options ContractDurableDispatchOptions) (runtimeapi.ExecutionReceipt, error)

func DurableSchedule added in v0.3.2 

func DurableSchedule(ctx context.Context, service, taskName, id string, every time.Duration, input []byte) error

func DurableSignal added in v0.3.2 

func DurableSignal(ctx context.Context, service, jobID, name, dedupeKey string, payload []byte) error

func DurableStep added in v0.3.2 

func DurableStep(ctx context.Context, key string, run func(context.Context) ([]byte, error)) ([]byte, error)

func ExecuteContractCLIRequest added in v0.3.2 

func ExecuteContractCLIRequest(path string, output io.Writer) error

func InitializeServices 

func InitializeServices() error

func InvokeContractBinding added in v0.3.2 

func InvokeContractBinding(ctx context.Context, address string, invocation, input any) (any, error)

func InvokeContractBindingFrom added in v0.3.2 

func InvokeContractBindingFrom(ctx context.Context, address, callerPackage string, invocation, input any) (any, error)

func InvokeContractBindingJSON added in v0.3.2 

func InvokeContractBindingJSON(ctx context.Context, address, callerPackage string, input []byte) ([]byte, error)

func InvokeContractPageJSON added in v0.3.2 

func InvokeContractPageJSON(ctx context.Context, pageAddress, action string, input []byte) ([]byte, error)

InvokeContractPageJSON executes a page load when action is empty, otherwise the named page action. The caller must provide a runtime invocation context; page dispatch cannot mint or forge a principal.

func InvokeContractPolicy added in v0.3.2 

func InvokeContractPolicy(ctx context.Context, policy *ContractHTTPPolicy, input any, invoke func(context.Context) (any, error)) (any, error)

func InvokeCronJob 

func InvokeCronJob(ctx context.Context, job *CronJob, scheduledAt time.Time, executionID string) error

func ListenAddrFromEnv 

func ListenAddrFromEnv() string

func ListenNetworkFromEnv 

func ListenNetworkFromEnv() string

func LoadDotEnvIntoEnv 

func LoadDotEnvIntoEnv() error

func MCPFederationReadiness added in v0.3.6 

func MCPFederationReadiness(serverAddress string) error

MCPFederationReadiness reports the current required-connection readiness. It samples the live federation snapshot so a background refresh can clear an earlier outage without another registration or process restart.

func Main 

func Main(cfg AppConfig) error

func MarkServiceInitialized 

func MarkServiceInitialized(service string, shutdown func(context.Context))

func MarkServiceInitializedWithError added in v0.3.2 

func MarkServiceInitializedWithError(service string, shutdown func(context.Context) error)

func Meta 

func Meta() *shared.AppMetadata

func PopulateContractContext added in v0.3.2 

func PopulateContractContext(input any, mappings []ContractContextMapping) error

func PopulateContractContextJSON added in v0.3.2 

func PopulateContractContextJSON(input []byte, mappings []ContractContextMapping) ([]byte, error)

PopulateContractContextJSON merges runtime-trusted context into a record before generated decoding enforces required fields and type constraints.

func PublishContractOperationOutcome added in v0.3.2 

func PublishContractOperationOutcome(ctx context.Context, operationAddress string, outcome any) error

func RegisterAssistant added in v0.3.6 

func RegisterAssistant(registration AssistantRegistration)

RegisterAssistant registers a generated assistant and its five raw public endpoints. It panics on invalid generated composition, matching the other convenience registration functions in this package.

func RegisterAssistantChecked added in v0.3.6 

func RegisterAssistantChecked(registration AssistantRegistration) error

RegisterAssistantChecked validates and registers an assistant atomically at the runtime registry level. The endpoint registration is part of the same ContractRegistry snapshot taken during Seal.

func RegisterAssistantClient added in v0.3.6 

func RegisterAssistantClient(address string, client AssistantClient) error

RegisterAssistantClient replaces the helper client used by an already registered assistant. Supervision uses this hook to swap a restarted child without rebuilding the public router.

func RegisterAssistantMCPManifest added in v0.3.6 

func RegisterAssistantMCPManifest(assistantAddress, serverAddress string, manifestJSON []byte)

RegisterAssistantMCPManifest is the panic-on-invalid convenience for hand written compositions. Generated code uses the checked form.

func RegisterAssistantMCPManifestChecked added in v0.3.6 

func RegisterAssistantMCPManifestChecked(assistantAddress, serverAddress string, manifestJSON []byte) error

RegisterAssistantMCPManifestChecked binds the generated MCP manifest and its canonical federation owner to one assistant. The bytes are parsed and validated before they enter runtime state; generated callers cannot bypass the provider-neutral mcpcontract checks with a hand-written struct.

func RegisterAuthHandler 

func RegisterAuthHandler(handler *AuthHandler)

func RegisterContractCLIBinding added in v0.3.2 

func RegisterContractCLIBinding(registration ContractCLIBindingRegistration) error

func RegisterContractDurableExecution added in v0.3.2 

func RegisterContractDurableExecution(registration ContractDurableRegistration) error

func RegisterContractEventBus added in v0.3.2 

func RegisterContractEventBus(address string, bus ContractEventBus) error

func RegisterContractEventConsumer added in v0.3.2 

func RegisterContractEventConsumer(registration ContractEventConsumerRegistration) error

func RegisterContractEventEmission added in v0.3.2 

func RegisterContractEventEmission(registration ContractEventEmissionRegistration) error

func RegisterContractInternalBinding added in v0.3.2 

func RegisterContractInternalBinding(address string, invoke ContractInternalInvoke) error

func RegisterContractInternalBindingWithPolicy added in v0.3.2 

func RegisterContractInternalBindingWithPolicy(registration ContractInternalBindingRegistration) error

func RegisterContractPage added in v0.3.2 

func RegisterContractPage(registration ContractPageRegistration) error

func RegisterContractProviderABI added in v0.3.2 

func RegisterContractProviderABI(identity, abi string) error

RegisterContractProviderABI is called by a loaded provider runtime to attest the exact ABI it actually implements. Generated application requirements do not populate this registry.

func RegisterContractSchedule added in v0.3.2 

func RegisterContractSchedule(registration ContractScheduleRegistration) error

func RegisterCronJobChecked added in v0.3.2 

func RegisterCronJobChecked(job *CronJob) error

func RegisterDurableTaskChecked added in v0.3.2 

func RegisterDurableTaskChecked(task *DurableTask) error

func RegisterEmbeddedAssistantAssets added in v0.3.6 

func RegisterEmbeddedAssistantAssets(options AssistantProductionOptions, assets []AssistantEmbeddedAsset) error

RegisterEmbeddedAssistantAssets installs one deterministic production service. The generated composition calls this after assistant and MCP manifest registration; the service then installs verified assets, writes the strict runtime descriptor, and starts every helper before the private MCP gateway and bootstrap dependencies run.

func RegisterEndpoint 

func RegisterEndpoint(ep *Endpoint)

func RegisterEndpointChecked added in v0.3.2 

func RegisterEndpointChecked(ep *Endpoint) error

func RegisterMCPFederation added in v0.3.6 

func RegisterMCPFederation(registration MCPFederationRegistration)

RegisterMCPFederation is the panic-on-invalid convenience used by hand written generated compositions. Generated code should generally call the checked form so ContractRegistry can roll back atomically.

func RegisterMCPFederationChecked added in v0.3.6 

func RegisterMCPFederationChecked(registration MCPFederationRegistration) error

RegisterMCPFederationChecked validates one canonical mcp_server and registers its NativeService lifecycle. The service is not connected until InitializeServices runs, preserving ContractRegistry's apply/rollback boundary.

func RegisterMCPSecretResolver added in v0.3.6 

func RegisterMCPSecretResolver(storeAddress string, resolver MCPSecretResolver) error

RegisterMCPSecretResolver installs one provider-backed resolver for a canonical secret-store address. Resolvers are process-local capability registrations and are never serialized into manifests or errors.

func RegisterMCPTool added in v0.3.6 

func RegisterMCPTool(registration MCPToolRegistration) error

func RegisterNativeService added in v0.3.2 

func RegisterNativeService(registration NativeServiceRegistration) error

func SetAppConfig 

func SetAppConfig(cfg AppConfig)

func SetPublicBaseURL 

func SetPublicBaseURL(baseURL string)

func ShutdownServices 

func ShutdownServices(ctx context.Context) error

func TraceDBQueryEnd 

func TraceDBQueryEnd(ctx context.Context, commandTag string, rowsAffected int64, err error)

TraceDBQueryEnd finishes a database query trace started by TraceDBQueryStart.

func TraceDBQueryStart 

func TraceDBQueryStart(ctx context.Context, query string, argsCount int) context.Context

TraceDBQueryStart starts a child trace for a database query and returns a context carrying the query trace metadata for TraceDBQueryEnd.

func UnregisterAssistantClient added in v0.3.6 

func UnregisterAssistantClient(address string, expected ...AssistantClient) error

UnregisterAssistantClient removes the private helper client while keeping the public assistant endpoints registered. When expected is supplied, the removal is compare-and-swap semantics: a newer child installed by another supervisor lane is never removed by a stale cleanup callback.

func ValidateContractCLIResponse added in v0.3.2 

func ValidateContractCLIResponse(response ContractCLIResponse, expectedSpecRevision string) error

func VerifyLinkedContractBundle added in v0.3.2 

func VerifyLinkedContractBundle(contractRevision string) error

func WaitDurableTask added in v0.3.2 

func WaitDurableTask(ctx context.Context, run DurableRun) ([]byte, error)

func WithAuthContext 

func WithAuthContext(ctx context.Context, auth AuthInfo) context.Context

func WriteAssistantRuntimeConfig added in v0.3.6 

func WriteAssistantRuntimeConfig(path string, config AssistantRuntimeConfig) error

WriteAssistantRuntimeConfig writes the private supervisor descriptor map atomically with mode 0600. Unlike MarshalJSON, this explicit server-only writer includes control address/token fields because it is the handoff boundary to the generated app child; callers must never expose its bytes in public responses or diagnostics.

Types

type Access 

type Access = runtimeapi.Access

type AppConfig 

type AppConfig struct {
	Name          string
	ListenAddr    string
	Observability ObservabilityConfig
	Role          string
}

type AssistantAssetDescriptor added in v0.3.6 

type AssistantAssetDescriptor struct {
	Kind                 string `json:"kind"`
	SchemaRevision       string `json:"schema_revision"`
	AssistantAddress     string `json:"assistant_address"`
	Target               string `json:"target"`
	RuntimeRevision      string `json:"runtime_revision"`
	CapabilityRevision   string `json:"capability_revision"`
	NodeArchiveDigest    string `json:"node_archive_digest"`
	NodeTreeDigest       string `json:"node_tree_digest"`
	CapsuleArchiveDigest string `json:"capsule_archive_digest"`
	CapsuleTreeDigest    string `json:"capsule_tree_digest"`
	CapsuleEntry         string `json:"capsule_entry"`
	PackageLockDigest    string `json:"package_lock_digest"`
}

AssistantAssetDescriptor is the provider-neutral descriptor emitted by the generated assets package. Tree descriptor JSON is carried separately so the runtime can verify an archive before installation without extracting it speculatively or trusting only a digest string.

type AssistantBootstrap added in v0.3.6 

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

AssistantBootstrap owns helper client replacement and cleanup. It keeps public registrations intact while swapping only the private client pointer; an unavailable child therefore leaves the public surface alive and neutral.

func BootstrapAssistantRuntime added in v0.3.6 

func BootstrapAssistantRuntime(ctx context.Context) (*AssistantBootstrap, error)

BootstrapAssistantRuntime is the generated-app entry point. It creates a provider-neutral client manager, reads the one descriptor seam, verifies health/info revisions, and leaves unavailable assistants neutral.

func NewAssistantBootstrap added in v0.3.6 

func NewAssistantBootstrap(options AssistantBootstrapOptions) *AssistantBootstrap

NewAssistantBootstrap constructs a manager without reading process environment or making network requests.

func (*AssistantBootstrap) Apply added in v0.3.6 

func (bootstrap *AssistantBootstrap) Apply(ctx context.Context, config AssistantRuntimeConfig) error

Apply probes every configured helper and atomically commits successful clients. Failed probes remove any old client for that assistant; no capability request can continue using a stale child after a restart.

func (*AssistantBootstrap) Close added in v0.3.6 

func (bootstrap *AssistantBootstrap) Close() error

Close unregisters every managed helper client and is idempotent. Public assistant endpoints remain registered and return the neutral unavailable response after cleanup.

func (*AssistantBootstrap) Statuses added in v0.3.6 

func (bootstrap *AssistantBootstrap) Statuses() []AssistantBootstrapStatus

Statuses returns a stable, provider-neutral snapshot sorted by assistant address. Private descriptor fields are never present in the result.

type AssistantBootstrapDescriptor added in v0.3.6 

type AssistantBootstrapDescriptor struct {
	AssistantAddress   string `json:"assistant_address"`
	ControlAddress     string `json:"-"`
	ControlToken       string `json:"-"`
	MCPListenAddress   string `json:"-"`
	MCPBridgeSecret    string `json:"-"`
	RuntimeRevision    string `json:"runtime_revision"`
	CapabilityRevision string `json:"capability_revision"`
	Required           bool   `json:"required"`
}

AssistantBootstrapDescriptor is one private helper endpoint descriptor. ControlAddress and ControlToken are server-only values. MarshalJSON omits both so status, diagnostics, and accidental config serialization cannot disclose a private address or credential.

func (AssistantBootstrapDescriptor) MarshalJSON added in v0.3.6 

func (descriptor AssistantBootstrapDescriptor) MarshalJSON() ([]byte, error)

MarshalJSON never includes the private helper address or control token.

func (*AssistantBootstrapDescriptor) UnmarshalJSON added in v0.3.6 

func (descriptor *AssistantBootstrapDescriptor) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts private descriptor fields only at the server-side config boundary. The custom method is deliberately paired with MarshalJSON below so credentials and loopback addresses never serialize.

type AssistantBootstrapOptions added in v0.3.6 

type AssistantBootstrapOptions struct {
	Factory      AssistantClientFactory
	ProbeTimeout time.Duration
}

AssistantBootstrapOptions configures the provider-neutral bootstrap manager. Zero values use the real HTTP client factory and a bounded probe timeout.

type AssistantBootstrapStatus added in v0.3.6 

type AssistantBootstrapStatus struct {
	AssistantAddress   string `json:"assistant_address"`
	State              string `json:"state"`
	Required           bool   `json:"required"`
	RuntimeRevision    string `json:"runtime_revision,omitempty"`
	CapabilityRevision string `json:"capability_revision,omitempty"`
	ErrorCode          string `json:"error_code,omitempty"`
}

AssistantBootstrapStatus is safe for provider-neutral inspection. It deliberately contains no control address, token, process details, or implementation/provider identity.

func AssistantRuntimeStatuses added in v0.3.6 

func AssistantRuntimeStatuses() []AssistantBootstrapStatus

AssistantRuntimeStatuses returns the active bootstrap snapshot for provider-neutral inspection. If startup has not run yet, declared assistants are reported as unconfigured without exposing any private descriptor data.

type AssistantClient added in v0.3.6 

type AssistantClient = assistantruntime.Client

AssistantClient is the provider-neutral managed-helper boundary consumed by the public Scenery assistant gateway.

type AssistantClientFactory added in v0.3.6 

type AssistantClientFactory func(AssistantBootstrapDescriptor) (AssistantClient, error)

AssistantClientFactory is injectable only to keep runtime bootstrap tests deterministic. Production uses the provider-neutral HTTP client factory.

type AssistantEmbeddedAsset added in v0.3.6 

type AssistantEmbeddedAsset struct {
	Descriptor            AssistantAssetDescriptor
	DescriptorJSON        []byte
	NodeArchive           []byte
	NodeDescriptorJSON    []byte
	CapsuleArchive        []byte
	CapsuleDescriptorJSON []byte
}

AssistantEmbeddedAsset is the generated-code-safe production asset input. Generated packages should copy their immutable embedded byte slices before calling RegisterEmbeddedAssistantAssets; this function never mutates them.

type AssistantProductionOptions added in v0.3.6 

type AssistantProductionOptions struct {
	StateRoot     string
	ApplicationID string
}

AssistantProductionOptions controls the private production state root. An empty StateRoot uses SCENERY_APP_ROOT/.scenery/assistant-runtime, or a deterministic user-cache path keyed by ApplicationID when no app root is available, so no arbitrary working directory becomes runtime state.

type AssistantRegistration added in v0.3.6 

type AssistantRegistration struct {
	Address            string
	Name               string
	Path               string
	Access             Access
	Policy             *ContractHTTPPolicy
	AssistantAddress   string
	RuntimeRevision    string
	CapabilityRevision string
	// Required defaults to true for every declared assistant. The private
	// bootstrap may still report an unavailable child without terminating the
	// Go app; this flag is for provider-neutral inspection and orchestration.
	Required        bool
	Client          AssistantClient
	TokenManager    assistanttoken.Manager
	InitiatorSigner assistanttoken.InitiatorSigner
	// RunIDReader and Random are testable entropy sources. Random is used for
	// request IDs when RunIDReader is not supplied.
	RunIDReader io.Reader
	Random      io.Reader
	// contains filtered or unexported fields
}

AssistantRegistration is emitted by generated application composition. The registration is applied before the contract registry seals, so the normal runtime snapshot/rollback transaction also covers assistant routes.

type AssistantRuntimeConfig added in v0.3.6 

type AssistantRuntimeConfig struct {
	Assistants []AssistantBootstrapDescriptor `json:"assistants"`
}

AssistantRuntimeConfig is the strict provider-neutral descriptor map supplied by the supervisor/production launcher. A missing file means all declared assistants remain registered but unavailable.

func LoadAssistantRuntimeConfig added in v0.3.6 

func LoadAssistantRuntimeConfig(path string) (AssistantRuntimeConfig, error)

LoadAssistantRuntimeConfig reads one strict descriptor file. Unknown fields, duplicate JSON members, trailing values, and oversized files fail closed before any helper client is touched.

func LoadAssistantRuntimeConfigFromEnv added in v0.3.6 

func LoadAssistantRuntimeConfigFromEnv() (AssistantRuntimeConfig, error)

LoadAssistantRuntimeConfigFromEnv reads the configured descriptor path. An unset seam is valid and produces an empty config (all assistants remain neutral/unavailable).

func (AssistantRuntimeConfig) Validate added in v0.3.6 

func (config AssistantRuntimeConfig) Validate() error

Validate checks the complete descriptor set before any client is created. It does not probe the helper; an unavailable or revision-mismatched helper is represented as an unavailable assistant while the Go app remains alive.

type AuthHandler 

type AuthHandler struct {
	Name         string
	Service      string
	Authenticate func(context.Context, string) (AuthInfo, error)
}

type AuthInfo 

type AuthInfo struct {
	UID  string
	Data any
}

func CurrentAuth 

func CurrentAuth() *AuthInfo

type ByteStat 

type ByteStat = runtimeapi.ByteStat

type CPUStats 

type CPUStats = runtimeapi.CPUStats

type ContractAuthorizationRule added in v0.3.2 

type ContractAuthorizationRule struct {
	Name       string
	Effect     string
	Expression string
}

type ContractBodyMapping added in v0.3.2 

type ContractBodyMapping struct {
	Codec                    string
	Target                   string
	Type                     string
	DecodeValue              func([]byte, any) error
	Include                  []string
	Except                   []string
	AcceptedMediaTypes       []string
	SupportedContentEncoding []string
	MaxCompressedBytes       int64
	MaxDecompressedBytes     int64
	Fields                   []ContractInputMapping
	MultipartParts           []ContractMultipartPart
	MaxMultipartParts        int
}

type ContractCLIBindingRegistration added in v0.3.2 

type ContractCLIBindingRegistration struct {
	Address string
	Command []string
	Policy  *ContractHTTPPolicy
	Invoke  ContractCLIInvoke
}

type ContractCLIInvoke added in v0.3.2 

type ContractCLIInvoke func(context.Context, []byte) (ContractCLIOutcome, error)

type ContractCLIOutcome added in v0.3.2 

type ContractCLIOutcome struct {
	Kind    string          `json:"kind"`
	Name    string          `json:"name"`
	Payload json.RawMessage `json:"payload"`
}

func InvokeContractCLIBinding added in v0.3.2 

func InvokeContractCLIBinding(ctx context.Context, address string, input []byte) (ContractCLIOutcome, error)

type ContractCLIRequest added in v0.3.2 

type ContractCLIRequest struct {
	Kind           string           `json:"kind"`
	SchemaRevision string           `json:"schema_revision"`
	SpecRevision   string           `json:"spec_revision"`
	Producer       machine.Producer `json:"producer"`
	Binding        string           `json:"binding"`
	Input          json.RawMessage  `json:"input"`
}

type ContractCLIResponse added in v0.3.2 

type ContractCLIResponse struct {
	Kind           string                    `json:"kind"`
	SchemaRevision string                    `json:"schema_revision"`
	SpecRevision   string                    `json:"spec_revision"`
	Producer       machine.Producer          `json:"producer"`
	Outcome        *ContractCLIOutcome       `json:"outcome,omitempty"`
	Problem        *ContractCLISystemProblem `json:"problem,omitempty"`
}

type ContractCLISystemProblem added in v0.3.2 

type ContractCLISystemProblem struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type ContractContextMapping added in v0.3.2 

type ContractContextMapping struct {
	Source string
	Target string
}

type ContractDecodedRequest added in v0.3.2 

type ContractDecodedRequest struct {
	Payload  any
	PathArgs []any
}

type ContractDurableDispatchOptions added in v0.3.2 

type ContractDurableDispatchOptions struct {
	DedupeKey      string
	ConcurrencyKey string
}

type ContractDurableRegistration added in v0.3.2 

type ContractDurableRegistration struct {
	Address                string
	ExternalName           string
	EngineAddress          string
	Service                string
	Revision               uint32
	DefaultTimeout         time.Duration
	DefaultLease           time.Duration
	MaxAttempts            int
	RetryInitial           time.Duration
	RetryMax               time.Duration
	RetryBackoff           float64
	RetryJitter            float64
	SuccessRetention       time.Duration
	FailureRetention       time.Duration
	MaxConcurrency         int
	DeduplicationRetention time.Duration
	DeduplicationConflict  string
	Handler                func(context.Context, []byte) ([]byte, error)
}

ContractDurableRegistration is the exact runtime projection of one scenery.execution durable execution.

type ContractEventBus added in v0.3.2 

type ContractEventBus interface {
	Publish(context.Context, ContractEventMessage) error
	Subscribe(context.Context, ContractEventSubscription) (func(context.Context) error, error)
}

type ContractEventConsumerRegistration added in v0.3.2 

type ContractEventConsumerRegistration struct {
	Address           string
	BusAddress        string
	Channel           string
	ContractAddress   string
	ContractVersion   uint32
	Guarantee         string
	Identity          string
	Attempts          int
	Backoff           string
	DeadLetterChannel string
	Policy            *ContractHTTPPolicy
	Invoke            func(context.Context, []byte) error
}

type ContractEventEmissionRegistration added in v0.3.2 

type ContractEventEmissionRegistration struct {
	Address           string
	OperationAddress  string
	BusAddress        string
	Channel           string
	ContractAddress   string
	ContractVersion   uint32
	Guarantee         string
	Attempts          int
	Backoff           string
	DeadLetterChannel string
	Encode            func(any) ([]byte, bool, error)
	OrderingKey       func(any) (string, error)
	DeduplicationKey  func(any) (string, error)
}

type ContractEventMessage added in v0.3.2 

type ContractEventMessage struct {
	ID                string            `json:"id,omitempty"`
	BusAddress        string            `json:"bus_address"`
	Channel           string            `json:"channel"`
	ContractAddress   string            `json:"contract_address"`
	ContractVersion   uint32            `json:"contract_version"`
	Guarantee         string            `json:"guarantee,omitempty"`
	OrderingKey       string            `json:"ordering_key,omitempty"`
	DeduplicationKey  string            `json:"deduplication_key,omitempty"`
	Attempts          int               `json:"attempts,omitempty"`
	Backoff           string            `json:"backoff,omitempty"`
	DeadLetterChannel string            `json:"dead_letter_channel,omitempty"`
	Attributes        map[string]string `json:"attributes,omitempty"`
	Payload           []byte            `json:"payload"`
}

type ContractEventRuntime added in v0.3.2 

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

func StartContractEventRuntime added in v0.3.2 

func StartContractEventRuntime(ctx context.Context) (*ContractEventRuntime, error)

func (*ContractEventRuntime) Stop added in v0.3.2 

func (running *ContractEventRuntime) Stop(ctx context.Context) error

type ContractEventSubscription added in v0.3.2 

type ContractEventSubscription struct {
	Address           string
	BusAddress        string
	Channel           string
	ContractAddress   string
	ContractVersion   uint32
	Guarantee         string
	Attempts          int
	Backoff           string
	DeadLetterChannel string
	Handle            func(context.Context, ContractEventMessage) error
}

type ContractHTTPPolicy added in v0.3.2 

type ContractHTTPPolicy struct {
	BindingAddress              string
	GatewayAddress              string
	CORS                        string
	AllowedOrigins              []string
	Forwarded                   string
	TrustedProxyPrefixes        []string
	MaxRequestHeaderBytes       int64
	MaxResponseBytes            int64
	CompressionAlgorithms       []string
	CompressionThreshold        int64
	TotalInvocationTimeoutNanos int64
	ReadTimeoutNanos            int64
	WriteTimeoutNanos           int64
	IdleTimeoutNanos            int64
	AuthorizationStrategy       string
	AuthorizationRuleCount      int
	AuthorizationRules          []ContractAuthorizationRule
	PipelineSteps               []string
	FrameworkGuarantee          string
	TransportStatuses           map[string]int
}

type ContractHTTPResponse added in v0.3.2 

type ContractHTTPResponse struct {
	Status  int
	Headers http.Header
	Body    []byte
}

func EncodeContractJSON added in v0.3.2 

func EncodeContractJSON(status int, value any) (ContractHTTPResponse, error)

func EncodeContractJSONForRequest added in v0.3.2 

func EncodeContractJSONForRequest(request *http.Request, status int, value any, produced []string, maxBytes int64) (ContractHTTPResponse, error)

func EncodeContractRepresentationForRequest added in v0.3.2 

func EncodeContractRepresentationForRequest(request *http.Request, status int, value any, codec string, produced []string, maxBytes int64) (ContractHTTPResponse, error)

func EncodeContractRepresentationWithOptions added in v0.3.2 

func EncodeContractRepresentationWithOptions(request *http.Request, status int, value any, codec string, produced []string, options ContractResponseOptions) (ContractHTTPResponse, error)

type ContractInputMapping added in v0.3.2 

type ContractInputMapping struct {
	Source     string
	Name       string
	Target     string
	Type       string
	Encoding   string
	Optional   bool
	EnumValues []string
}

type ContractInternalBindingRegistration added in v0.3.2 

type ContractInternalBindingRegistration struct {
	Address      string
	Visibility   string
	Package      string
	Policy       *ContractHTTPPolicy
	DecodeInput  func([]byte) (any, error)
	EncodeOutput func(any) ([]byte, error)
	Invoke       ContractInternalInvoke
}

type ContractInternalInvoke added in v0.3.2 

type ContractInternalInvoke func(context.Context, any, any) (any, error)

type ContractMultipartPart added in v0.3.2 

type ContractMultipartPart struct {
	Name           string
	Target         string
	Type           string
	Kind           string
	MediaTypes     []string
	MaxBytes       int64
	Multiple       bool
	Optional       bool
	RetainFilename bool
}

type ContractPageRegistration added in v0.3.2 

type ContractPageRegistration struct {
	Address     string                         `json:"address"`
	Package     string                         `json:"package"`
	Path        string                         `json:"path"`
	LoadBinding string                         `json:"load_binding"`
	Actions     map[string]string              `json:"actions"`
	Renderers   []ContractRendererRegistration `json:"renderers"`
}

func ContractPages added in v0.3.2 

func ContractPages() []ContractPageRegistration

type ContractPathTail added in v0.3.2 

type ContractPathTail struct {
	CanonicalTemplate string
	Name              string
	Target            string
	Type              string
	EmptyCapture      string
	MinimumSegments   int
	Decoding          string
	Guarantee         string
	Precedence        []string
}

type ContractRegistration added in v0.3.2 

type ContractRegistration struct {
	ContractRevision           string
	PackageContractABIRevision string
	RuntimeABI                 string
	ProviderABIs               map[string]string
	CoveredAddresses           []string
	Apply                      func() error
}

ContractRegistration is the application-adapter payload accepted by the contract registration boundary. Apply is delayed until Seal has verified the complete ownership set, so missing or duplicate adapters cannot expose a partial runtime graph.

type ContractRegistry added in v0.3.2 

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

func NewContractRegistry added in v0.3.2 

func NewContractRegistry(options ContractRegistryOptions) (*ContractRegistry, error)

func (*ContractRegistry) Register added in v0.3.2 

func (registry *ContractRegistry) Register(address string, implementation any) error

func (*ContractRegistry) Seal added in v0.3.2 

func (registry *ContractRegistry) Seal() error

type ContractRegistryOptions added in v0.3.2 

type ContractRegistryOptions struct {
	ContractRevision  string
	RequiredAddresses []string
	ProviderABIs      map[string]string
}

type ContractRendererRegistration added in v0.3.2 

type ContractRendererRegistration struct {
	Address              string `json:"address"`
	Runtime              string `json:"runtime"`
	Module               string `json:"module"`
	ImplementationDigest string `json:"implementation_digest"`
	ConfigJSON           string `json:"config_json,omitempty"`
}

type ContractRequestSchema added in v0.3.2 

type ContractRequestSchema struct {
	Mappings          []ContractInputMapping
	ContextMappings   []ContractContextMapping
	Body              *ContractBodyMapping
	TransportStatuses map[string]int
}

type ContractResponseCookie added in v0.3.2 

type ContractResponseCookie struct {
	Name     string
	Path     string
	Domain   string
	MaxAge   int
	Expires  string
	Secure   bool
	HTTPOnly bool
	SameSite http.SameSite
}

type ContractResponseOptions added in v0.3.2 

type ContractResponseOptions struct {
	MaxBytes              int64
	CompressionAlgorithms []string
	CompressionThreshold  int64
	TypeExpression        string
	EncodeValue           func(any) ([]byte, error)
}

type ContractResponseValueOptions added in v0.3.2 

type ContractResponseValueOptions struct {
	Encoding    string
	EncodeValue func(any) ([]byte, error)
}

type ContractScheduleRegistration added in v0.3.2 

type ContractScheduleRegistration struct {
	Address              string
	Name                 string
	TriggerKind          string
	TriggerValue         string
	Timezone             string
	Overlap              string
	CatchupMaximumAge    time.Duration
	Identity             ContractWorkloadIdentity
	AuthorizationAddress string
	PipelineAddress      string
	Policy               *ContractHTTPPolicy
	Invoke               func(context.Context) error
}

type ContractTransportError added in v0.3.2 

type ContractTransportError struct {
	Outcome string
	Status  int
	Message string
	Cause   error
}

func (*ContractTransportError) Error added in v0.3.2 

func (e *ContractTransportError) Error() string

func (*ContractTransportError) Unwrap added in v0.3.2 

func (e *ContractTransportError) Unwrap() error

type ContractWorkloadIdentity added in v0.3.2 

type ContractWorkloadIdentity struct {
	Address       string
	Issuer        string
	PrincipalType string
	ClaimsJSON    string
}

func (ContractWorkloadIdentity) Mint added in v0.3.2 

func (identity ContractWorkloadIdentity) Mint() (AuthInfo, error)

type CronJob 

type CronJob struct {
	ID             string
	Title          string
	Every          time.Duration
	Schedule       string
	Calendar       string
	At             time.Time
	Timezone       string
	OverlapPolicy  string
	CatchupWindow  time.Duration
	PauseOnFailure bool
	Invoke         func(context.Context) error
	// contains filtered or unexported fields
}

type DiskStats 

type DiskStats = runtimeapi.DiskStats

type DurableExecutionFailure added in v0.3.2 

type DurableExecutionFailure struct {
	Service  string
	ID       string
	State    string
	TaskName string
}

func (*DurableExecutionFailure) Error added in v0.3.2 

func (failure *DurableExecutionFailure) Error() string

type DurableRun added in v0.3.2 

type DurableRun struct {
	ID        string
	Service   string
	TaskName  string
	State     string
	DedupeKey string
}

func StartDurableTask added in v0.3.2 

func StartDurableTask(ctx context.Context, req DurableStartRequest) (DurableRun, error)

type DurableStartRequest added in v0.3.2 

type DurableStartRequest struct {
	Service        string
	TaskName       string
	ID             string
	DedupeKey      string
	ConcurrencyKey string
	Input          any
}

type DurableTask added in v0.3.2 

type DurableTask struct {
	Name                   string
	Service                string
	Version                int
	HandlerRef             string
	Handler                func(context.Context, []byte) ([]byte, error)
	DefaultTimeout         time.Duration
	DefaultLease           time.Duration
	MaxAttempts            int
	RetryInitial           time.Duration
	RetryMax               time.Duration
	RetryBackoff           float64
	RetryJitter            float64
	SuccessRetention       time.Duration
	FailureRetention       time.Duration
	MaxConcurrency         int
	DeduplicationRetention time.Duration
	DeduplicationConflict  string
	RequirementsJSON       string
}

type Endpoint 

type Endpoint struct {
	Service               string
	Name                  string
	Access                Access
	Raw                   bool
	Path                  string
	Methods               []string
	Invoke                func(context.Context, []any, any) (any, error)
	RawHandler            func(http.ResponseWriter, *http.Request)
	DecodeContractRequest func(*http.Request, map[string]string) (ContractDecodedRequest, error)
	EncodeContractOutcome func(*http.Request, any) (ContractHTTPResponse, error)
	ContractPolicy        *ContractHTTPPolicy
	ContractPathTail      *ContractPathTail
}

type EndpointFilterConfig 

type EndpointFilterConfig struct {
	IncludeEndpoints []string
	ExcludeEndpoints []string
}

type GCStats 

type GCStats = runtimeapi.GCStats

type GoStats 

type GoStats = runtimeapi.GoStats

type LinkedContractBundle added in v0.3.2 

type LinkedContractBundle struct {
	ContractRevision       string
	ImplementationRevision string
	BuildInputDigest       string
	GoTarget               string
}

func CurrentLinkedContractBundle added in v0.3.2 

func CurrentLinkedContractBundle() LinkedContractBundle

type MCPConnectionSpec added in v0.3.6 

type MCPConnectionSpec struct {
	Address   string
	Namespace string
	URL       string
	Required  bool
	Allow     []string
	Block     []string

	ConnectTimeout time.Duration
	CallTimeout    time.Duration
	RefreshTTL     time.Duration

	AuthScheme string
	AuthHeader string
	Secret     MCPSecretReference
}

MCPConnectionSpec is the deployment-time description of one external MCP connection. Auth credentials can only be supplied through Secret; there is no plaintext credential field in this generated-code-safe type.

type MCPDurableReceipt added in v0.3.6 

type MCPDurableReceipt = mcpcontract.DurableReceipt

MCPDurableReceipt is the public runtime name for the provider-neutral receipt returned by a durable tool.

type MCPDurableRequest added in v0.3.6 

type MCPDurableRequest struct {
	Principal   string
	Service     string
	TaskName    string
	ExecutionID string
}

MCPDurableRequest identifies a receipt and principal for status/cancel.

type MCPDurableStatus added in v0.3.6 

type MCPDurableStatus struct {
	Service      string          `json:"service"`
	TaskName     string          `json:"task_name"`
	ExecutionID  string          `json:"execution_id"`
	State        string          `json:"state"`
	Result       json.RawMessage `json:"result,omitempty"`
	ErrorMessage string          `json:"error,omitempty"`
}

MCPDurableStatus is the ownership-filtered durable state view.

type MCPFederatedCapability added in v0.3.6 

type MCPFederatedCapability = mcpcontract.Capability

MCPFederatedCapability is the public runtime alias for the provider-neutral capability consumed by the private MCP gateway. It carries no URL or auth material.

type MCPFederation added in v0.3.6 

type MCPFederation interface {
	Ready() bool
	Capabilities() []MCPFederatedCapability
	CallTool(context.Context, MCPToolCallContext, string, json.RawMessage) (MCPToolOutcome, error)
}

MCPFederation is the narrow runtime lookup surface used to construct a private mcpgateway.Config. Implementations expose only the current, policy-projected inventory and dispatch; connection credentials remain inside the federation owner.

func LookupAssistantMCPFederation added in v0.3.6 

func LookupAssistantMCPFederation(assistantAddress string) (MCPFederation, bool)

LookupAssistantMCPFederation resolves the shared federation for an assistant address.

func LookupMCPFederation added in v0.3.6 

func LookupMCPFederation(serverAddress string) (MCPFederation, bool)

LookupMCPFederation resolves a canonical mcp_server after initialization.

func LookupMCPFederationForAssistant added in v0.3.6 

func LookupMCPFederationForAssistant(assistantAddress string) (MCPFederation, bool)

LookupMCPFederationForAssistant is an explicit alias for generated callers that prefer the lookup target in the function name.

type MCPFederationReadinessError added in v0.3.6 

type MCPFederationReadinessError struct {
	ServerAddress       string
	RequiredUnavailable []string
}

MCPFederationReadinessError is retained for a required-connection outage. It is deliberately opaque: callers can inspect the typed error and use the federation's Ready method without receiving URLs, network text, or secrets.

func (*MCPFederationReadinessError) Error added in v0.3.6 

func (e *MCPFederationReadinessError) Error() string

func (*MCPFederationReadinessError) Unwrap added in v0.3.6 

func (e *MCPFederationReadinessError) Unwrap() error

type MCPFederationRegistration added in v0.3.6 

type MCPFederationRegistration struct {
	Address            string
	AssistantAddresses []string
	CapabilityRevision string
	LocalToolNames     []string
	MaxInputBytes      int64
	MaxResultBytes     int64
	Connections        []MCPConnectionSpec
}

MCPFederationRegistration describes one canonical mcp_server and the assistants that share its remote inventory. All assistant lookups for the same server return the same federation instance; assistant authorization and assertions are still enforced by the private gateway.

type MCPSecretReference added in v0.3.6 

type MCPSecretReference struct {
	ResourceAddress string
	StoreAddress    string
	Key             string
}

MCPSecretReference identifies a framework secret without carrying its value. StoreAddress and ResourceAddress are canonical Scenery addresses; Key is the provider-defined value key.

type MCPSecretResolver added in v0.3.6 

type MCPSecretResolver func(context.Context, MCPSecretReference) ([]byte, error)

MCPSecretResolver is registered by a provider-backed secret store. The resolver receives symbolic metadata only and returns a short-lived copy of the secret for one federation startup/refresh. Runtime errors never include the returned bytes.

type MCPToolCallContext added in v0.3.6 

type MCPToolCallContext = mcpcontract.ToolCallContext

MCPToolCallContext is the public runtime name for the provider-neutral contract context. Keeping this alias lets generated external applications construct calls without importing Scenery's internal contract package.

type MCPToolDispatcher added in v0.3.6 

type MCPToolDispatcher struct{}

MCPToolDispatcher resolves generated registrations and runs them with the same runtime auth, invocation, policy, and cancellation machinery as HTTP or internal contract calls.

func (MCPToolDispatcher) CallTool added in v0.3.6 

func (MCPToolDispatcher) CallTool(ctx context.Context, call MCPToolCallContext, name string, input json.RawMessage) (MCPToolOutcome, error)

func (MCPToolDispatcher) Cancel added in v0.3.6 

func (dispatcher MCPToolDispatcher) Cancel(ctx context.Context, call MCPToolCallContext, executionID string) (json.RawMessage, error)

Cancel exposes the framework-owned durable cancel shape expected by the private MCP gateway and enforces the same principal ownership check as DurableStatus.

func (MCPToolDispatcher) CancelDurable added in v0.3.6 

func (MCPToolDispatcher) CancelDurable(ctx context.Context, request MCPDurableRequest) error

CancelDurable cancels only a receipt owned by the principal that accepted it.

func (MCPToolDispatcher) DurableStatus added in v0.3.6 

func (MCPToolDispatcher) DurableStatus(ctx context.Context, request MCPDurableRequest) (MCPDurableStatus, error)

DurableStatus returns state only to the principal that accepted the receipt.

func (MCPToolDispatcher) Status added in v0.3.6 

func (dispatcher MCPToolDispatcher) Status(ctx context.Context, call MCPToolCallContext, executionID string) (json.RawMessage, error)

Status exposes the framework-owned durable status shape expected by the private MCP gateway. A raw execution ID is never sufficient to read another principal's job; the owner map remains the authorization source.

type MCPToolEffect added in v0.3.6 

type MCPToolEffect struct {
	ReadOnly    bool
	Destructive bool
	Idempotent  bool
	OpenWorld   bool
}

MCPToolEffect records the compiler's provider-neutral effect hints.

type MCPToolLimits added in v0.3.6 

type MCPToolLimits struct {
	MaxInputBytes  int64
	MaxResultBytes int64
}

MCPToolLimits are enforced before generated codecs or handlers run.

type MCPToolOutcome added in v0.3.6 

type MCPToolOutcome = mcpcontract.ToolOutcome

MCPToolOutcome is the public runtime name for the provider-neutral tool outcome. MCPToolResult remains an alias for callers of the initial runtime bridge API.

type MCPToolRegistration added in v0.3.6 

type MCPToolRegistration struct {
	ID                 string
	Name               string
	AssistantAddress   string
	CapabilityRevision string
	OperationAddress   string
	ExecutionAddress   string
	Policy             *ContractHTTPPolicy
	Limits             MCPToolLimits
	Effect             MCPToolEffect
	Approval           string
	Durable            bool
	DurableService     string
	DurableTask        string
	DecodeInput        func([]byte) (any, error)
	EncodeOutput       func(any) ([]byte, error)
	Invoke             func(context.Context, MCPToolCallContext, any) (any, error)
}

MCPToolRegistration is emitted by generated composition. Invoke must call the generated service adapter (or its durable dispatch path), never a native implementation directly.

type MCPToolResult added in v0.3.6 

type MCPToolResult = mcpcontract.ToolOutcome

type MemoryStats 

type MemoryStats = runtimeapi.MemoryStats

type NativeServiceRegistration added in v0.3.2 

type NativeServiceRegistration struct {
	Address      string
	Dependencies []string
	Initialize   func(context.Context) error
	Shutdown     func(context.Context) error
}

type OSProcessStats 

type OSProcessStats = runtimeapi.OSProcessStats

type ObservabilityConfig 

type ObservabilityConfig struct {
	Logs    EndpointFilterConfig
	Tracing EndpointFilterConfig
}

type ParamKind 

type ParamKind = runtimeapi.ParamKind

type ParamSpec 

type ParamSpec = runtimeapi.ParamSpec

type PlatformStatsResponse 

type PlatformStatsResponse = runtimeapi.PlatformStatsResponse

type ProcessStats 

type ProcessStats = runtimeapi.ProcessStats
type ProfileLinks = runtimeapi.ProfileLinks

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.