sdk

package
v0.1.0-preview.4 Latest Latest
Warning

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

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

Documentation

Overview

Package sdk defines the stable, statically decoded Spice annotation descriptor contract. Descriptor functions are ordinary Go declarations, but the Spice compiler reads their composite literals without executing them.

Index

Constants

View Source 
const (
	TargetPackage   = annotation.TargetPackage
	TargetType      = annotation.TargetType
	TargetFunction  = annotation.TargetFunction
	TargetMethod    = annotation.TargetMethod
	TargetParameter = annotation.TargetParameter
	TargetVariable  = annotation.TargetVariable
	TargetConstant  = annotation.TargetConstant
)
View Source 
const (
	KindString     = annotation.KindString
	KindInteger    = annotation.KindInteger
	KindBoolean    = annotation.KindBoolean
	KindIdentifier = annotation.KindIdentifier
	KindList       = annotation.KindList
)
View Source 
const (
	// ValueDomainNone uses only the argument's lexical Kinds metadata.
	ValueDomainNone = annotation.ValueDomainNone
	// ValueDomainGoInterface accepts named runtime Go interface type
	// expressions resolved from the consuming application's typed program.
	ValueDomainGoInterface = annotation.ValueDomainGoInterface
)
View Source 
const (
	// FunctionResultFactNamespace reserves invocation facts that describe the
	// ordered results of one ordinary Go function declaration.
	FunctionResultFactNamespace = "go.function.results."
	// FunctionResultCountFact is the required result count when the function
	// result fact set is present.
	FunctionResultCountFact = FunctionResultFactNamespace + "count"
	// MaximumFunctionResultFacts bounds one function signature transported to
	// an annotation handler.
	MaximumFunctionResultFacts = 64
	// MaximumFunctionResultTypeIDBytes bounds each readable type identity.
	MaximumFunctionResultTypeIDBytes = 32 << 10
)

Variables

This section is empty.

Functions

func BeanIdentity 

func BeanIdentity(
	arguments BoundArguments,
) (string, []string, error)

BeanIdentity decodes the conventional optional name and aliases arguments used by constructible bean descriptors. An explicitly empty name is rejected; aliases are validated by the contribution boundary.

func EncodeFunctionResultFacts 

func EncodeFunctionResultFacts(
	results []FunctionResultFact,
) (map[string]string, error)

EncodeFunctionResultFacts returns a new deterministic fact set for the complete ordered result list. A zero-result function is represented by an explicit count of zero.

func PositionalIdentifiers 

func PositionalIdentifiers(
	invocation Invocation,
) ([]string, error)

PositionalIdentifiers validates and decodes an invocation made exclusively from one or more positional Go identifier expressions.

Types

type ApplicationContribution 

type ApplicationContribution struct{}

ApplicationContribution marks the invocation target as an application marker. The compiler derives roots from the target's exact Go signature.

type Argument 

type Argument struct {
	Name             string
	Kinds            []Kind
	ListElementKinds []Kind
	ValueDomain      ValueDomain
	AllowedValues    []string
	Description      string
	Default          string
	Required         bool
	Positional       bool
	Variadic         bool
}

Argument describes one supported annotation argument.

type AsyncContribution 

type AsyncContribution struct{}

AsyncContribution marks a method for generated asynchronous execution.

type AuthorizationContribution 

type AuthorizationContribution struct {
	Authenticated bool     `json:"authenticated,omitempty"`
	AnyRoles      []string `json:"any_roles,omitempty"`
	AllRoles      []string `json:"all_roles,omitempty"`
	AllScopes     []string `json:"all_scopes,omitempty"`
	Expression    string   `json:"expression,omitempty"`
}

AuthorizationContribution describes one secure-deny route policy.

type BeanMetadataContribution 

type BeanMetadataContribution struct {
	Qualifiers []string  `json:"qualifiers,omitempty"`
	Primary    bool      `json:"primary,omitempty"`
	Fallback   bool      `json:"fallback,omitempty"`
	Order      *int64    `json:"order,omitempty"`
	Scope      BeanScope `json:"scope,omitempty"`
}

BeanMetadataContribution adds selection and ownership metadata to a bean or one constructor parameter. Qualifiers on parameters are requests; all other fields describe the bean on the annotated declaration.

type BeanScope 

type BeanScope string

BeanScope identifies which generated owner controls a bean instance and its cleanup. Scope values are compiler inputs, not runtime string lookups. 

const (
	BeanScopeSingleton BeanScope = "singleton"
	BeanScopePrototype BeanScope = "prototype"
	BeanScopeRequest   BeanScope = "request"
	BeanScopeSession   BeanScope = "session"
)

type BootstrapContribution 

type BootstrapContribution struct {
	Capability string            `json:"capability"`
	Options    []BootstrapOption `json:"options,omitempty"`
}

BootstrapContribution activates one application-platform capability with deterministic string metadata owned by the handler.

type BootstrapOption 

type BootstrapOption struct {
	Name  string            `json:"name"`
	Value ContributionValue `json:"value"`
}

BootstrapOption is one named, typed capability setting.

type BoundArguments 

type BoundArguments map[string]InvocationArgument

BoundArguments is a validated name-to-value annotation argument map.

func BindArguments 

func BindArguments(
	invocation Invocation,
	positional string,
	allowed ...string,
) (BoundArguments, error)

BindArguments rejects unsupported, duplicate, and malformed argument names.

func (BoundArguments) Boolean 

func (arguments BoundArguments) Boolean(name string) (bool, error)

Boolean returns a decoded Boolean argument.

func (BoundArguments) Identifier 

func (arguments BoundArguments) Identifier(
	name string,
	required bool,
) (string, error)

Identifier returns one decoded Go identifier expression argument.

func (BoundArguments) Integer 

func (arguments BoundArguments) Integer(name string) (int64, error)

Integer returns a decoded integer argument.

func (BoundArguments) String 

func (arguments BoundArguments) String(
	name string,
	required bool,
) (string, error)

String returns a decoded string argument.

func (BoundArguments) Strings 

func (arguments BoundArguments) Strings(name string) ([]string, error)

Strings returns a decoded string-list argument.

type CacheContribution 

type CacheContribution struct {
	Name string `json:"name"`
}

CacheContribution describes one named generated cache boundary.

type Compatibility 

type Compatibility struct {
	Since        string
	MinimumSpice string
}

Compatibility documents the public lifecycle of an annotation contract.

type ConfigurationContribution 

type ConfigurationContribution struct {
	Prefix string `json:"prefix,omitempty"`
}

ConfigurationContribution marks one typed configuration declaration. Prefix is empty or a dot-separated sequence of lowercase identifier segments. Each segment may contain digits after its first letter and single interior hyphens, for example "agent.runtime-plugin".

type Contribution 

type Contribution struct {
	Kind           ContributionKind
	Application    *ApplicationContribution
	Stereotype     *StereotypeContribution
	Interface      *InterfaceBindingContribution
	Provider       *ProviderContribution
	BeanMetadata   *BeanMetadataContribution
	Configuration  *ConfigurationContribution
	Enum           *EnumContribution
	Controller     *ControllerContribution
	Route          *RouteContribution
	Module         *ModuleContribution
	NamedInterface *NamedInterfaceContribution
	Lifecycle      *LifecycleContribution
	Bootstrap      *BootstrapContribution
	Schedule       *ScheduleContribution
	Async          *AsyncContribution
	Transaction    *TransactionContribution
	EventTopic     *EventTopicContribution
	EventListener  *EventListenerContribution
	Cache          *CacheContribution
	Authorization  *AuthorizationContribution
	Retry          *RetryContribution
	Observation    *ObservationContribution
	GeneratedFile  *GeneratedFileContribution
}

Contribution is a discriminated typed SDK union. Exactly one payload matching Kind must be present.

func (Contribution) Clone 

func (contribution Contribution) Clone() Contribution

Clone returns a deep defensive copy.

func (Contribution) Validate 

func (contribution Contribution) Validate() error

Validate rejects malformed, ambiguous, or unknown contribution payloads.

type ContributionKind 

type ContributionKind string

ContributionKind identifies one typed compiler-IR input returned by an annotation handler. 

const (
	ContributionApplication    ContributionKind = "application"
	ContributionStereotype     ContributionKind = "stereotype"
	ContributionInterface      ContributionKind = "interface-binding"
	ContributionProvider       ContributionKind = "provider"
	ContributionBeanMetadata   ContributionKind = "bean-metadata"
	ContributionConfiguration  ContributionKind = "configuration"
	ContributionEnum           ContributionKind = "enum"
	ContributionController     ContributionKind = "controller"
	ContributionRoute          ContributionKind = "route"
	ContributionModule         ContributionKind = "module"
	ContributionNamedInterface ContributionKind = "named-interface"
	ContributionLifecycle      ContributionKind = "lifecycle"
	ContributionBootstrap      ContributionKind = "bootstrap"
	ContributionSchedule       ContributionKind = "schedule"
	ContributionAsync          ContributionKind = "async"
	ContributionTransaction    ContributionKind = "transaction"
	ContributionEventTopic     ContributionKind = "event-topic"
	ContributionEventListener  ContributionKind = "event-listener"
	ContributionCache          ContributionKind = "cache"
	ContributionAuthorization  ContributionKind = "authorization"
	ContributionRetry          ContributionKind = "retry"
	ContributionObservation    ContributionKind = "observation"
	ContributionGeneratedFile  ContributionKind = "generated-file"
)

type ContributionValue 

type ContributionValue struct {
	Kind       Kind                `json:"kind"`
	String     string              `json:"string,omitempty"`
	Integer    int64               `json:"integer,omitempty"`
	Boolean    bool                `json:"boolean,omitempty"`
	Identifier string              `json:"identifier,omitempty"`
	List       []ContributionValue `json:"list,omitempty"`
}

ContributionValue is a recursively typed literal safe for SDK transport.

type ControllerContribution 

type ControllerContribution struct {
	Prefix string `json:"prefix,omitempty"`
}

ControllerContribution marks one HTTP controller declaration.

type Declaration 

type Declaration struct {
	Target          Target `json:"target"`
	SymbolID        string `json:"symbol_id"`
	Name            string `json:"name"`
	PackagePath     string `json:"package_path"`
	TypeID          string `json:"type_id,omitempty"`
	ParameterIndex  int    `json:"parameter_index,omitempty"`
	ParameterName   string `json:"parameter_name,omitempty"`
	ParameterTypeID string `json:"parameter_type_id,omitempty"`
}

Declaration contains normalized, non-executable facts about an annotation target. Type identities are import-path-qualified strings.

type Definition 

type Definition struct {
	Name           string
	Summary        string
	Targets        []Target
	Repeatable     bool
	Arguments      []Argument
	Examples       []Example
	Compatibility  Compatibility
	Implementation Implementation
}

Definition is the complete public, inspectable annotation descriptor.

func (Definition) Validate 

func (definition Definition) Validate() error

Validate fails closed on incomplete or ambiguous descriptor metadata.

type EnumContribution 

type EnumContribution struct{}

EnumContribution marks one named scalar type whose same-file constants form its complete legal value set. The compiler derives members and underlying values from the typed Go program.

type EventListenerContribution 

type EventListenerContribution struct {
	Order int64 `json:"order,omitempty"`
}

EventListenerContribution describes one ordered typed event listener.

type EventTopicContribution 

type EventTopicContribution struct{}

EventTopicContribution marks a typed event topic provider.

type Example 

type Example struct {
	Title string
	Code  string
}

Example is one documentation example shown by editors and generated GoDoc.

type FunctionResultFact 

type FunctionResultFact struct {
	TypeID             string
	CanonicalTypeID    string
	Kind               GoTypeKind
	NamedOriginPackage string
	NamedOriginName    string
}

FunctionResultFact is one ordered, non-executable function result fact. TypeID preserves the readable source identity, including a declared alias. CanonicalTypeID is the same type after top-level alias removal. Kind classifies its effective underlying type. NamedOriginPackage and NamedOriginName identify the declaration that owns an unaliased named type, including the origin of an instantiation.

func DecodeFunctionResultFacts 

func DecodeFunctionResultFacts(
	facts map[string]string,
) ([]FunctionResultFact, bool, error)

DecodeFunctionResultFacts validates and decodes the reserved result fact namespace. The Boolean is false for a v1alpha2 invocation produced before these optional map entries existed. Unrelated invocation facts are ignored.

func (FunctionResultFact) Validate 

func (fact FunctionResultFact) Validate() error

Validate rejects malformed or unbounded function result metadata.

type GeneratedFileContribution 

type GeneratedFileContribution struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

GeneratedFileContribution requests one guarded generated file. The compiler still owns path safety, generated markers, ownership, and filesystem apply.

type GoTypeKind 

type GoTypeKind string

GoTypeKind classifies the effective Go type after aliases are removed and a named type is reduced to its underlying kind. It is intentionally independent of any annotation or framework. 

const (
	GoTypeArray         GoTypeKind = "array"
	GoTypeBasic         GoTypeKind = "basic"
	GoTypeChannel       GoTypeKind = "channel"
	GoTypeInterface     GoTypeKind = "interface"
	GoTypeMap           GoTypeKind = "map"
	GoTypePointer       GoTypeKind = "pointer"
	GoTypeSignature     GoTypeKind = "signature"
	GoTypeSlice         GoTypeKind = "slice"
	GoTypeStruct        GoTypeKind = "struct"
	GoTypeTuple         GoTypeKind = "tuple"
	GoTypeTypeParameter GoTypeKind = "type-parameter"
	GoTypeUnion         GoTypeKind = "union"
)

type Handler 

type Handler func(context.Context, Invocation) (Result, error)

Handler is the exact executable contract implemented by one annotation. Descriptor source stores a package-level function of this type. The compiler validates and identifies that symbol statically; it never calls the function.

type HandlerDiagnostic 

type HandlerDiagnostic struct {
	Code     string `json:"code"`
	Severity string `json:"severity"`
	Message  string `json:"message"`
}

HandlerDiagnostic is one annotation-handler-owned source diagnostic.

type Implementation 

type Implementation struct {
	Tool     string
	Handler  Handler
	Protocol ProtocolVersion
}

Implementation identifies the native tool handler behind a descriptor.

type InterfaceBindingContribution 

type InterfaceBindingContribution struct {
	Interfaces []string `json:"interfaces"`
}

InterfaceBindingContribution explicitly exposes one concrete bean through named Go interfaces. Expressions are resolved against the invocation's physical source file by the typed compiler; handlers never guess method assignability.

type Invocation 

type Invocation struct {
	DescriptorPackage string               `json:"descriptor_package"`
	DescriptorSymbol  string               `json:"descriptor_symbol"`
	CanonicalName     string               `json:"canonical_name"`
	Arguments         []InvocationArgument `json:"arguments,omitempty"`
	Declaration       Declaration          `json:"declaration"`
	Facts             map[string]string    `json:"facts,omitempty"`
}

Invocation is one normalized explicit descriptor invocation. Facts is an extensible v1alpha2 string map: SDK-owned namespaces add bounded semantic metadata without changing the wire struct seen by older strict decoders.

func (Invocation) FunctionResultFacts 

func (invocation Invocation) FunctionResultFacts() (
	[]FunctionResultFact,
	bool,
	error,
)

FunctionResultFacts decodes the generic result metadata attached to this invocation. See DecodeFunctionResultFacts for absence behavior.

func (Invocation) RequireDescriptor 

func (invocation Invocation) RequireDescriptor(
	packagePath string,
	symbol string,
) error

RequireDescriptor rejects dispatch to a handler for another descriptor.

type InvocationArgument 

type InvocationArgument struct {
	Name       string          `json:"name,omitempty"`
	Kind       Kind            `json:"kind"`
	Positional bool            `json:"positional,omitempty"`
	Value      json.RawMessage `json:"value"`
}

InvocationArgument retains parsed spelling and a normalized JSON value.

type Kind 

type Kind = annotation.Kind

Kind identifies an accepted annotation argument representation.

type LifecycleContribution 

type LifecycleContribution struct {
	Phase LifecyclePhase `json:"phase"`
}

LifecycleContribution describes one start or stop callback.

type LifecyclePhase 

type LifecyclePhase string

LifecyclePhase identifies when a lifecycle callback runs. 

const (
	LifecycleStart LifecyclePhase = "start"
	LifecycleStop  LifecyclePhase = "stop"
)

type ModuleContribution 

type ModuleContribution struct {
	AllowedDependencies []string `json:"allowed_dependencies,omitempty"`
}

ModuleContribution describes one application module root.

type NamedInterfaceContribution 

type NamedInterfaceContribution struct {
	Name string `json:"name"`
}

NamedInterfaceContribution exposes one named module API.

type ObservationContribution 

type ObservationContribution struct {
	Name string `json:"name,omitempty"`
}

ObservationContribution describes one generated method observation. Name is optional; an empty name selects the compiler-owned stable method ID.

type ProtocolVersion 

type ProtocolVersion string

ProtocolVersion identifies a compatible native plugin protocol. 

const (
	// ProtocolV1Alpha2 is the typed-handler stdio plugin contract.
	ProtocolV1Alpha2 ProtocolVersion = "spice.annotation/v1alpha2"
)

type ProviderContribution 

type ProviderContribution struct {
	Name    string   `json:"name,omitempty"`
	Aliases []string `json:"aliases,omitempty"`
}

ProviderContribution marks the invocation target as a provider. The compiler derives inputs, output, cleanup, and error behavior from go/types.

type Result 

type Result struct {
	Contributions []Contribution
	Diagnostics   []HandlerDiagnostic
}

Result is the typed, transport-independent output of one Handler call.

func Contributions 

func Contributions(values ...Contribution) (Result, error)

Contributions validates and returns one deterministic handler result.

func OneContribution 

func OneContribution(value Contribution) (Result, error)

OneContribution validates and returns a result containing one contribution.

type RetryContribution 

type RetryContribution struct {
	MaxAttempts    int64  `json:"max_attempts"`
	InitialBackoff string `json:"initial_backoff,omitempty"`
	MaxBackoff     string `json:"max_backoff,omitempty"`
	Multiplier     int64  `json:"multiplier,omitempty"`
	Classifier     string `json:"classifier,omitempty"`
}

RetryContribution describes one bounded generated method retry policy. Classifier is an optional exported package function with signature func(error) bool; an empty classifier selects retry.Transient.

type RouteContribution 

type RouteContribution struct {
	Method string `json:"method"`
	Path   string `json:"path"`
}

RouteContribution describes one generated HTTP route.

type ScheduleContribution 

type ScheduleContribution struct {
	Delay           string `json:"delay"`
	InitialDelay    string `json:"initial_delay,omitempty"`
	ContinueOnError bool   `json:"continue_on_error,omitempty"`
}

ScheduleContribution describes one fixed-delay scheduled method.

type StereotypeContribution 

type StereotypeContribution struct {
	Role        string   `json:"role"`
	Construct   bool     `json:"construct,omitempty"`
	Constructor string   `json:"constructor,omitempty"`
	Name        string   `json:"name,omitempty"`
	Aliases     []string `json:"aliases,omitempty"`
}

StereotypeContribution classifies a declaration for architecture and tooling without inventing construction behavior. Providers remain explicit.

type Symbol 

type Symbol struct {
	Package string
	Name    string
}

Symbol identifies one real Go declaration.

type Target 

type Target = annotation.Target

Target identifies an allowed declaration target.

type TransactionContribution 

type TransactionContribution struct {
	Isolation string `json:"isolation,omitempty"`
	ReadOnly  bool   `json:"read_only,omitempty"`
}

TransactionContribution describes one generated transaction boundary.

type ValueDomain 

type ValueDomain = annotation.ValueDomain

ValueDomain identifies an SDK-defined semantic value space. Domains let the shared Spice compiler provide type-aware validation, completion, navigation, and code actions without an editor or compiler switch on an annotation name.

Source Files

View all Source files

Directories

Path Synopsis
Package protocol defines the versioned framed stdio contract shared by Spice annotation tools and the compiler host.
 Package protocol defines the versioned framed stdio contract shared by Spice annotation tools and the compiler host.
Package sdktest provides deterministic black-box tests for annotation SDK descriptors and handlers.
 Package sdktest provides deterministic black-box tests for annotation SDK descriptors and handlers.
Package starter defines deterministic compatibility and annotation metadata for opt-in Spice integrations.
 Package starter defines deterministic compatibility and annotation metadata for opt-in Spice integrations.

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.