Documentation
¶
Overview ¶
Package sub is used for subscribing to handle requests. It contains the options to use in Connector.Subscribe
Index ¶
- Constants
- type HTTPHandler
- type Option
- func At(method string, route string) Option
- func Automatic() Option
- func DefaultQueue() Option
- func Description(text string) Option
- func Function(inputs any, outputs any) Option
- func InboundEvent(inputs any, outputs any) Option
- func Manual() Option
- func Method(method string) Option
- func NoQueue() Option
- func NoTrace() Option
- func Queue(queue string) Option
- func RequiredClaims(boolExp string) Option
- func Route(route string) Option
- func Tag(tags ...string) Option
- func Task(inputs any, outputs any) Option
- func TimeBudget(d time.Duration) Option
- func Trace() Option
- func Untag(tags ...string) Option
- func Web() Option
- func Workflow(inputs any, outputs any) Option
- type Subscription
Constants ¶
const ( TypeFunction = "function" TypeWeb = "web" TypeInboundEvent = "inboundevent" TypeTask = "task" TypeWorkflow = "workflow" )
Type values identify the kind of a Microbus endpoint behind a subscription.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HTTPHandler ¶
type HTTPHandler func(w http.ResponseWriter, r *http.Request) (err error)
HTTPHandler extends the standard http.Handler to also return an error.
type Option ¶
type Option func(sub *Subscription) error
Option is used to construct a subscription in Connector.Subscribe
func At ¶ added in v1.27.0
At sets both the method and the route of a subscription in a single option. It is shorthand for Method followed by Route. Same method validation rules apply.
func Automatic ¶ added in v1.30.0
func Automatic() Option
Automatic clears the Manual flag, restoring the default automatic activate/deactivate behavior.
func DefaultQueue ¶
func DefaultQueue() Option
DefaultQueue names the queue of this subscription to the hostname of the service. Requests will be load-balanced among all instances of this microservice.
func Description ¶ added in v1.27.0
Description sets a human-readable description for the subscription. Used by the built-in OpenAPI handler.
func Function ¶ added in v1.27.0
Function declares the subscription as a typed function (RPC) endpoint. The inputs and outputs values are zero-value struct instances used for OpenAPI schema reflection.
func InboundEvent ¶ added in v1.27.0
InboundEvent declares the subscription as an inbound event sink. The inputs and outputs values are zero-value struct instances used for OpenAPI schema reflection.
func Manual ¶ added in v1.30.0
func Manual() Option
Manual opts the subscription out of the connector's automatic activate/deactivate passes. User code drives its lifecycle via [connector.Connector.ActivateSubscription] and [connector.Connector.DeactivateSubscription].
func Method ¶ added in v1.27.0
Method overrides the default "ANY" method for a Listen subscription. Accepts one of the recognized HTTP methods (GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH) or "ANY" to match any method. Matching is case-insensitive; the value is normalized to uppercase. Returns an error at option-application time if the method is not recognized.
func NoQueue ¶
func NoQueue() Option
NoQueue sets no queue for this subscription. Requests will be not be load-balanced, all instances of this microservice will receive the request
func NoTrace ¶ added in v1.28.0
func NoTrace() Option
NoTrace suppresses OpenTelemetry span creation for this subscription. Requests handled by this subscription will not appear in distributed traces. Useful for high-frequency or internal subscriptions that would otherwise add noise to traces.
func Queue ¶
Queue names the queue of the subscription. Requests will be load-balanced among all consumers with the same queue name
func RequiredClaims ¶ added in v1.22.0
RequiredClaims requires that the properties of the actor associated with the request satisfy the boolean expression. For example: iss=='my_issuer' && (roles.admin || roles.manager) && region=="US". The =~ and !~ operators evaluate the left operand against a regexp. String constants, including regexp patterns, must be quoted using single quotes, double quotes or backticks. A request that doesn't satisfy the constraint is denied with a 403 forbidden error.
func Route ¶ added in v1.27.0
Route overrides the default ":443/my-subscription" route for a Listen subscription. If the route does not include a hostname, it is resolved relative to the microservice's default hostname. If a port is not specified, 443 is used by default. Port 0 is used to designate any port. Path arguments are designated by curly braces.
Examples of valid routes:
(empty)
/
/path
:1080
:1080/
:1080/path
:0/any/port
/path/with/slash
path/with/no/slash
/section/{section}/page/{page...}
https://www.example.com/path
https://www.example.com:1080/path
//www.example.com:1080/path
func Tag ¶ added in v1.30.0
Tag attaches one or more free-form labels to the subscription. Tags are surfaced through [connector.Connector.Subscriptions] and let user code group related subscriptions for activation, deactivation, or other bulk operations. Tag names are not parsed by the framework; convention is short, lowercase, hyphen-or-dot-free identifiers (e.g. "python", "billing", "experimental"). Multiple calls accumulate; duplicates are preserved as written.
func Task ¶ added in v1.27.0
Task declares the subscription as a workflow task endpoint. The inputs and outputs values are zero-value struct instances used for OpenAPI schema reflection.
func TimeBudget ¶ added in v1.32.0
TimeBudget declares the maximum duration the endpoint's handler may run. The inbound request's context deadline is shortened to the smaller of the caller-provided budget and this declared budget. A zero or negative duration declares no budget. The deadline binds only this handler's own context; it does not change what an upstream caller waits.
func Trace ¶ added in v1.28.0
func Trace() Option
Trace clears the NoTrace flag, restoring the default behavior where each handled request creates an OpenTelemetry server span.
func Untag ¶ added in v1.30.0
Untag removes one or more tags previously attached with Tag. Tags not currently set are silently ignored. Provided for symmetry with Tag in programmatically composed option lists.
type Subscription ¶
type Subscription struct {
Name string
Description string
Host string
Port string
Method string
Path string
Queue string
Handler any
Subs []*transport.Subscription
RequiredClaims string
TimeBudget time.Duration
Type string
Inputs any
Outputs any
Manual bool
NoTrace bool
Tags []string
// contains filtered or unexported fields
}
Subscription handles incoming requests. Although technically public, it is used internally and should not be constructed by microservices directly.
func NewSubscription ¶ added in v1.27.0
func NewSubscription(name string, defaultHost string, handler HTTPHandler, options ...Option) (*Subscription, error)
NewSubscription creates a new subscription registered by name. The name must be a legal Go-style upper-case identifier (e.g. "MyEndpoint2"). Exactly one feature option (Function, Web, InboundEvent, Task, [Graph]) must be supplied. Defaults filled in after options are applied:
- Method defaults to "ANY".
- Route defaults to ":<port>/<kebab-name>" with the port determined by the feature type (443 for function/web, 417 for inbound events, 428 for tasks/graphs).
- Queue defaults to defaultHost.
func (*Subscription) Apply ¶
func (sub *Subscription) Apply(options ...Option) error
Apply the provided options to the subscription.
func (*Subscription) Canonical ¶
func (sub *Subscription) Canonical() string
Canonical returns the fully-qualified canonical host:port/path of the subscription, not including the scheme or the method.
func (*Subscription) RefreshHostname ¶
func (sub *Subscription) RefreshHostname(defaultHost string) error
RefreshHostname refreshes the subscription for a different hostname.
Source Files