Documentation
¶
Overview ¶
Package client is the client tier: the one decoration every outbound client (an SDK, a datastore, an HTTP API) runs its operations through. Tier orders the layers; the decoration config (decoration.clients, built by decorate.Decorations) switches and tunes them per client; Base gives a client's decorated wrapper typed, per-operation helpers as generic methods; and Kinds is each family's backend table.
Index ¶
- func Call[In, Out, O any](b Base, op string, fn func(ctx context.Context, in In, opts ...O) (Out, error)) decorate.OpFunc[In, Out]
- func CallOnce[In, Out, O any](b Base, op string, fn func(ctx context.Context, in In, opts ...O) (Out, error)) decorate.OpFunc[In, Out]
- func Tier() decorate.Tier
- type Backend
- type Base
- func (b Base) Do(ctx context.Context, op string, fn func(context.Context) error) error
- func (b Base) DoOnce(ctx context.Context, op string, fn func(context.Context) error) error
- func (b Base) Once[R any](ctx context.Context, op string, fn func(context.Context) (R, error)) (R, error)
- func (b Base) Open[R any](ctx context.Context, op string, open func(context.Context) (R, error)) (R, error)
- func (b Base) Stream[R any](ctx context.Context, op string, open func(context.Context) (R, error)) (stream R, release func(), err error)
- type Kind
- type Kinds
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Call ¶ added in v0.0.12
func Call[In, Out, O any]( b Base, op string, fn func(ctx context.Context, in In, opts ...O) (Out, error), ) decorate.OpFunc[In, Out]
Call is the client's named idempotent call: the SDK function fn, shaped as an AWS SDK v2 operation (ctx, input, ...option), runs through the client tier with its retry, breaker, bulkhead and timeout. fn takes no options here; its client was configured when it was built.
Types ¶
type Backend ¶
Backend builds one Kind of a family from its Config C and Deps D into its interface T; ctx bounds any I/O the backend does to construct.
type Base ¶
type Base struct {
// Subject runs idempotent operations; it supplies Name and Exec.
decorate.Subject
// contains filtered or unexported fields
}
Base runs one client's operations through the client tier. Its embedded Exec runs an idempotent operation (retried when the tier retries); Once, Do and DoOnce cover the rest. The zero Base runs every operation undecorated.
func NewBaseFrom ¶ added in v0.0.12
func NewBaseFrom(decs decorate.Decorations, name string) (Base, error)
NewBaseFrom returns the Base for the client named name, decorated from decs: the client as the client-tier component name, and each named call op as name+"."+op. A decoration that fails to resolve is CodeInvalidInput.
func NewHandlerBase ¶
NewHandlerBase returns the Base for a consumer's message handlers, named name, over deps without its retry, breaker and bulkhead: a handler is observed (in consumer spans) and bounded, never retried or broken — the broker's redelivery is the retry, and one poison message must not trip the others.
func NewProducerBase ¶
NewProducerBase returns the Base for a message publisher named name over deps: the client tier with producer spans, since each operation sends a message to a broker.
func (Base) Once ¶
func (b Base) Once[R any]( ctx context.Context, op string, fn func(context.Context) (R, error), ) (R, error)
Once runs fn as the operation op without the retry layer: an operation that is not idempotent or consumes its input (an upload body, a create).
func (Base) Open ¶
func (b Base) Open[R any]( ctx context.Context, op string, open func(context.Context) (R, error), ) (R, error)
Open opens a long-lived stream as the operation op, bounding only the open: the client's timeout caps how long open may take, while the stream it returns lives on ctx with no deadline of the client's (a generation stream can outlast any call budget). The open is decorated (never retried); an open that overruns is abandoned — its context canceled — and returned as CodeTimeout.
func (Base) Stream ¶
func (b Base) Stream[R any]( ctx context.Context, op string, open func(context.Context) (R, error), ) (stream R, release func(), err error)
Stream opens a stream as the operation op. The open is decorated (never retried); the client's timeout bounds the stream's whole life, so the returned release must be called when the stream is closed. On error release is already done.
type Kind ¶
type Kind string
Kind names one backend of a client family, as written in config.
const KindStub Kind = "stub"
KindStub is the zero-infrastructure backend a family ships so its graph boots without I/O.
type Kinds ¶
type Kinds[C, D, T any] struct { // Backends maps each Kind to its constructor. Backends map[Kind]Backend[C, D, T] // Decorate wraps a backend in the client tier as the client named name. Decorate func(base T, name string, deps decorate.Deps) T // Family names the client family ("cache", "lock", …). Family string // Default is the Kind an empty config selects. Default Kind // AtMostOnce lists the kinds whose operations are at-most-once (a Redis PUBLISH): a // retry could repeat a delivery, so Build never retries them whatever the config says. AtMostOnce []Kind }
Kinds is a client family's backend table: Family labels its errors and names the client in the tier, Default is the backend an empty Kind selects, Backends builds each Kind from the family's Config C and Deps D into its interface T, and Decorate runs a built backend through the client tier.
func (Kinds[C, D, T]) Build ¶
func (k Kinds[C, D, T]) Build( ctx context.Context, kind Kind, cfg C, deps D, decs decorate.Decorations, name string, ) (T, error)
Build builds the backend kind names and runs it through the client tier as the client named name (Family when empty), its layers from decs; an AtMostOnce kind gets no retry.
Source Files