protocol

Documentation

Index

• Constants
• func CancelExecution(instanceID, executionID string) string
• func ExecutionByID(instanceID, executionID string) string
• func ExecutionEvents(instanceID, executionID string) string
• func ExecutionEventsStream(instanceID, executionID string) string
• func HashAssembly(assembly core.Assembly) (string, error)
• func HashBlueprint(value any) (string, error)
• func InstanceByID(instanceID string) string
• func InstanceExecutions(instanceID string) string
• func Method(method, template string) string
• type CancelExecutionRequest
• type CreateInstanceRequest
• type EventItem
• type ExecuteRequest
• type ExecuteResponse
• type ExecutionItem
• type ExecutionResult
• type InstanceKey
  • func AssemblyKey(assembly core.Assembly, env string) (InstanceKey, error)
  • func ParseKey(s string) (InstanceKey, error)
  • func ParseUserKey(s string) (InstanceKey, error)
  • func (k InstanceKey) ColonString() string
  • func (k InstanceKey) String() string
• type InstanceResponse
• type ListOptions
• type RegisterRequest
• type RegisterResponse
• type RegisterStatus
• type Response
• type StreamEvent

Constants

const (
	HealthPath                = "/health"
	InstancesPath             = "/v1/instances"
	InstanceByIDPath          = "/v1/instances/{id}"
	ExecutePath               = "/v1/instances/{id}/executions"
	ExecutionByIDPath         = "/v1/instances/{id}/executions/{execID}"
	ExecutionEventsPath       = "/v1/instances/{id}/executions/{execID}/events"
	ExecutionEventsStreamPath = "/v1/instances/{id}/executions/{execID}/events/stream"
	CancelExecutionPath       = "/v1/instances/{id}/executions/{execID}/cancel"

	WebSocketPath = "/v1/ws"

	RegisterPath = "/v1/register"
)

The route table for the N.O.R.E. local API.

These templates are the single description of every endpoint in this file, and they are written in the named-wildcard form Go's ServeMux registers, because the server is what ultimately has to serve them. The client cannot use the templates directly -- it needs a concrete URL -- so every parameterized template has a constructor below that substitutes the placeholders and escapes the values as path segments.

Both directions go through this one table on purpose. A client that hand-assembled a path, or a server that registered a literal, would agree with the other side only until one of them changed: nothing in the build would fail, and the mismatch would surface as a 404 or, worse, a silently dropped field.

const VersionLatest = "latest"

VersionLatest is the pseudo-version that resolves to the most recently registered version of an assembly. It is used when a key omits the version or explicitly asks for "latest". Resolution is time-based: whatever version was registered last wins, regardless of semver ordering.

Functions

func CancelExecution

func CancelExecution(instanceID, executionID string) string

CancelExecution returns the path addressing the cancellation of one execution.

func ExecutionByID

func ExecutionByID(instanceID, executionID string) string

ExecutionByID returns the path addressing a single execution.

func ExecutionEvents

func ExecutionEvents(instanceID, executionID string) string

ExecutionEvents returns the path addressing the persisted events of one execution.

func ExecutionEventsStream

func ExecutionEventsStream(instanceID, executionID string) string

ExecutionEventsStream returns the path addressing the live event stream of one execution.

func HashAssembly

func HashAssembly(assembly core.Assembly) (string, error)

HashAssembly returns a deterministic content hash for an Assembly.

The parser generates random IDs (assembly and binding metadata IDs) on every parse, so the raw struct cannot be hashed directly. HashAssembly normalizes the assembly first: generated IDs are dropped, capabilities and bindings are sorted, and map marshaling (key-sorted by encoding/json) stays stable.

func HashBlueprint

func HashBlueprint(value any) (string, error)

func InstanceByID

func InstanceByID(instanceID string) string

InstanceByID returns the path addressing a single instance.

func InstanceExecutions

func InstanceExecutions(instanceID string) string

InstanceExecutions returns the path addressing the execution collection of one instance.

func Method

func Method(method, template string) string

Method joins an HTTP method to a route template, producing the pattern Go's ServeMux registers.

It exists so a route's method and path are written as one expression. The space between them is part of ServeMux's pattern syntax rather than an accident, and spelling it out at every call site is how a method quietly ends up applied to the wrong path.

Types

type CancelExecutionRequest

type CancelExecutionRequest struct {
	// Reason is recorded on the cancellation. An empty reason is still a
	// legitimate cancellation; the handler substitutes its own wording.
	Reason string `json:"reason,omitempty"`
}

CancelExecutionRequest is the body of a request to cancel a running execution.

It is declared here because the client and the handler were each declaring the same body anonymously, which left the wire shape with no single owner: a field could be renamed on one side and the mismatch would surface as a silently ignored cancel reason rather than a compile error.

type CreateInstanceRequest

type CreateInstanceRequest struct {
	Key      InstanceKey    `json:"key"`
	Assembly *core.Assembly `json:"assemblies"`
}

type EventItem

type EventItem struct {
	ID           core.ID `json:"id"`
	Type         string  `json:"type"`
	CapabilityID core.ID `json:"capability_id"`
	Payload      any     `json:"payload"`
}

type ExecuteRequest

type ExecuteRequest struct {
	// Params is the free-form data passed to the execution's entry
	// capabilities.
	Params map[string]any `json:"params,omitempty"`
	// Mode selects how the server responds. "detach" returns immediately with
	// the execution accepted (HTTP 202); anything else (empty or "wait") waits
	// for the execution to finish and returns its final result (HTTP 200).
	Mode string `json:"mode,omitempty"`
}

type ExecuteResponse

type ExecuteResponse struct {
	ExecutionID core.ID   `json:"execution_id"`
	InstanceID  string    `json:"instance_id"`
	Status      string    `json:"status"`
	Time        time.Time `json:"time"`
}

type ExecutionItem

type ExecutionItem struct {
	ID            core.ID `json:"id"`
	CorrelationID core.ID `json:"correlation_id"`
	Status        string  `json:"status"`
	StartedAt     *int64  `json:"started_at,omitempty"`
	CompletedAt   *int64  `json:"completed_at,omitempty"`
	Error         string  `json:"error,omitempty"`

	// ParentExecutionID is set when this execution took over detached work from
	// another execution in the same instance. It lets a caller walk from a
	// detached task back to the execution whose caller handed the work off.
	ParentExecutionID core.ID `json:"parent_execution_id,omitempty"`
}

type ExecutionResult

type ExecutionResult struct {
	ExecutionID core.ID                   `json:"execution_id"`
	InstanceID  string                    `json:"instance_id"`
	Status      string                    `json:"status"`
	Error       string                    `json:"error,omitempty"`
	Results     map[string]map[string]any `json:"results,omitempty"`
}

ExecutionResult is returned by a wait-mode Execute request once the execution has reached a terminal state. Results aggregates every capability result keyed by capability ID.

type InstanceKey

type InstanceKey struct {
	AssemblyID string `json:"assembly_id"`
	Version    string `json:"version,omitempty"`
	Hash       string `json:"hash,omitempty"`
	Env        string `json:"env,omitempty"`
}

func AssemblyKey

func AssemblyKey(assembly core.Assembly, env string) (InstanceKey, error)

AssemblyKey derives the identity of an Assembly from its metadata. Hash is computed deterministically via HashAssembly.

func ParseKey

func ParseKey(s string) (InstanceKey, error)

ParseKey parses a colon-encoded InstanceKey: assemblyID[:version[:hash[:env]]]. Missing version and hash default to latest and ""; an omitted env is left empty so the server can resolve the registration regardless of environment.

func ParseUserKey

func ParseUserKey(s string) (InstanceKey, error)

ParseUserKey accepts the human-facing forms of an instance key and normalizes them to an InstanceKey:

• colon form: name[:version[:hash[:env]]] (see ParseKey)
• at form: name@version[#hash][:env]
• bare name: latest version is assumed

Instance IDs (inst_*) are NOT parsed here; callers that accept both should branch on the prefix before calling.

func (InstanceKey) ColonString

func (k InstanceKey) ColonString() string

ColonString renders the key in its colon-encoded wire form used in URL paths: assemblyID[:version[:hash[:env]]]. The version defaults to "latest", but an empty hash or environment is preserved as an empty segment so a partial key stays partial: the server then resolves the registration regardless of hash or environment instead of defaulting them itself.

func (InstanceKey) String

func (k InstanceKey) String() string

type InstanceResponse

type InstanceResponse struct {
	ID                string        `json:"id"`
	BlueprintMetadata core.Metadata `json:"blueprint_metadata"`
	Status            string        `json:"status"`
	AssemblyID        string        `json:"assembly_id"`
	Version           string        `json:"version,omitempty"`
	Hash              string        `json:"hash,omitempty"`
	Env               string        `json:"env,omitempty"`
}

type ListOptions

type ListOptions struct {
	Status string
	All    bool
}

type RegisterRequest

type RegisterRequest struct {
	Assembly core.Assembly `json:"assembly"`

	// Key is the client-computed identity (AssemblyID, Version, Hash, Env). When
	// provided the server validates Hash matches the assembly content; when
	// empty the server derives the key from the assembly metadata.
	Key InstanceKey `json:"key,omitempty"`

	// ExecutionConfigurations carries opaque capability-runtime-requirement
	// metadata that N.O.R.E. persists alongside the assembly for later runtime
	// assembly.
	ExecutionConfigurations any `json:"execution_configurations,omitempty"`

	// Force clears the registered assembly for the resolved name:version — and
	// removes any instances built from it — before registering the new one.
	Force bool `json:"force,omitempty"`
}

RegisterRequest registers an assembly definition durably with N.O.R.E. It does not create or start an Instance; instances are created lazily on the first execution request for the assembly's key.

type RegisterResponse

type RegisterResponse struct {
	Key     InstanceKey    `json:"key"`
	Status  RegisterStatus `json:"status"`
	Message string         `json:"message,omitempty"`
}

type RegisterStatus

type RegisterStatus string

RegisterStatus describes the outcome of a registration against a durable key.

const (
	RegisterStatusRegistered        RegisterStatus = "registered"
	RegisterStatusAlreadyRegistered RegisterStatus = "already_registered"
	RegisterStatusReplaced          RegisterStatus = "replaced"
)

type Response

type Response struct {
	Message string `json:"message"`
	Status  int    `json:"status"`
	Data    any    `json:"data,omitempty"`
}

Response Base wrapper to standardize all API replies

type StreamEvent

type StreamEvent struct {
	ID            core.ID         `json:"id"`
	Type          string          `json:"type"`
	CorrelationID core.ID         `json:"correlation_id,omitempty"`
	CapabilityID  core.ID         `json:"capability_id,omitempty"`
	OccurredAt    int64           `json:"occurred_at"`
	Payload       json.RawMessage `json:"payload,omitempty"`
}

StreamEvent is the canonical wire shape for both historical replay and live stream events emitted over the SSE endpoint.