Documentation
¶
Overview ¶
Package define is the vocabulary for a microservice's api package definition.go, where every feature the microservice exposes is declared as a define.* var: Function, Web, Task, Workflow, OutboundEvent, InboundEvent, Config, Metric, and Ticker. cmd/genservice generates the rest of the microservice from these declarations.
Write only statically resolvable values: literals, the In/Out/Value type carriers (e.g. In: FooIn{}, Value: int(0)), and references to other define.* vars (e.g. an InboundEvent's Source). Design rationale is in CLAUDE.md.
Index ¶
Constants ¶
const ( Default = "default" // explicit form of the hostname-named queue: load-balanced among all peers None = "none" // no queue: multicast to all peers )
LoadBalancing values for an endpoint's queue behavior. The empty string (the default) uses a queue named after the hostname, load-balancing requests among all peers.
const ( Counter = "counter" Gauge = "gauge" Histogram = "histogram" )
Metric kinds.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Value any // getter return type carrier: string(""), int(0), ..., time.Duration(0), or MyStruct{}
Default string // raw default string, as it would appear in YAML; empty means no default
Validation string // cfg validation applied to the raw string, e.g. "int [1,]", "url", "json"
Secret bool // never logged
Callback bool // OnChanged<Name> fires when the value changes
}
Config is a runtime configuration property, sourced as a string then converted to Value's Go type.
type Function ¶
type Function struct {
Host string // the api package's Hostname const
Method string // GET, POST, ..., or ANY
Route string // e.g. ":443/my-func" or "//host/path"
RequiredClaims string // boolean expression over JWT claims; empty means open
TimeBudget time.Duration // per-endpoint max duration; zero means the framework default
LoadBalancing string // "" (default), define.None, or a custom queue name
Manual bool // registered via sub.Manual(); brought online later with svc.ActivateSubscription(name)
Tags []string // sub.Tag labels for grouping subscriptions (e.g. "python")
In any // the FooIn{} struct, as a type carrier
Out any // the FooOut{} struct, as a type carrier
}
Function is a unicast or multicast request-response RPC endpoint.
type InboundEvent ¶
type InboundEvent struct {
Source OutboundEvent // the source microservice's OutboundEvent var
RequiredClaims string // boolean expression over JWT claims; empty means open
TimeBudget time.Duration // per-endpoint max duration; zero means the framework default
LoadBalancing string // "" (default), define.None, or a custom queue name
Manual bool // registered via sub.Manual(); brought online later with svc.ActivateSubscription(name)
Tags []string // sub.Tag labels for grouping subscriptions (e.g. "python")
}
InboundEvent subscribes this microservice to an event fired by another. Source references the source microservice's OutboundEvent var, so a removed or renamed event is a compile error here. The Service method that handles the event is named after the InboundEvent var.
type Metric ¶
type Metric struct {
Kind string // define.Counter | define.Gauge | define.Histogram
Value any // recorder value type carrier: a numeric conversion, e.g. int(0) or float64(0)
Labels []string // label parameter names (string-typed)
Buckets []float64 // histogram bucket boundaries
OTelName string // the OpenTelemetry metric name
Observable bool // measured just-in-time via the OnObserve<Name> callback
}
Metric is a counter, gauge, or histogram.
type OutboundEvent ¶
type OutboundEvent struct {
Host string // the api package's Hostname const
Method string // GET, POST, ..., or ANY
Route string // e.g. ":417/on-my-event"
RequiredClaims string // boolean expression over JWT claims; empty means open
TimeBudget time.Duration // per-endpoint max duration; zero means the framework default
LoadBalancing string // "" (default), define.None, or a custom queue name
In any // the FooIn{} struct, as a type carrier
Out any // the FooOut{} struct, as a type carrier
}
OutboundEvent is an event this microservice fires for subscribers to consume.
func (OutboundEvent) URL ¶
func (e OutboundEvent) URL() string
URL is the full URL of the endpoint, joined with its Host.
type Task ¶
type Task struct {
Host string // the api package's Hostname const
Method string // GET, POST, ..., or ANY
Route string // e.g. ":443/my-func" or "//host/path"
RequiredClaims string // boolean expression over JWT claims; empty means open
TimeBudget time.Duration // per-endpoint max duration; zero means the framework default
LoadBalancing string // "" (default), define.None, or a custom queue name
Manual bool // registered via sub.Manual(); brought online later with svc.ActivateSubscription(name)
Tags []string // sub.Tag labels for grouping subscriptions (e.g. "python")
In any // the FooIn{} struct, as a type carrier
Out any // the FooOut{} struct, as a type carrier
}
Task is a workflow task endpoint, invoked with a *workflow.Flow carrier.
type Web ¶
type Web struct {
Host string // the api package's Hostname const
Method string // GET, POST, ..., or ANY
Route string // e.g. ":443/my-func" or "//host/path"
RequiredClaims string // boolean expression over JWT claims; empty means open
TimeBudget time.Duration // per-endpoint max duration; zero means the framework default
LoadBalancing string // "" (default), define.None, or a custom queue name
Manual bool // registered via sub.Manual(); brought online later with svc.ActivateSubscription(name)
Tags []string // sub.Tag labels for grouping subscriptions (e.g. "python")
}
Web is a raw http.ResponseWriter / *http.Request handler endpoint. It carries no In/Out.
type Workflow ¶
type Workflow struct {
Host string // the api package's Hostname const
Method string // GET, POST, ..., or ANY
Route string // e.g. ":443/my-func" or "//host/path"
RequiredClaims string // boolean expression over JWT claims; empty means open
TimeBudget time.Duration // per-endpoint max duration; zero means the framework default
LoadBalancing string // "" (default), define.None, or a custom queue name
Manual bool // registered via sub.Manual(); brought online later with svc.ActivateSubscription(name)
Tags []string // sub.Tag labels for grouping subscriptions (e.g. "python")
In any // the FooIn{} struct, as a type carrier
Out any // the FooOut{} struct, as a type carrier
}
Workflow is a workflow graph endpoint.
Source Files