Documentation
¶
Overview ¶
Package entclient is the CALLER side of an entity kind: bind a definition to a Temporal client, then drive the entity — Exec commands, Read queries, Describe, Delete. Command/query values are the request types themselves (entity.Command / entity.Query); call sites carry no strings and no explicit type parameters.
Index ¶
- func ApplyRaw(ctx context.Context, c client.Client, kind entity.KindName, ...) (string, error)
- func DescribeRaw(ctx context.Context, c client.Client, workflowID string) (json.RawMessage, error)
- func Exec[Spec, State, Res any, Req entity.Command[Res]](ctx context.Context, cl *Client[Spec, State], id entity.ResourceID, req Req) (Res, error)
- func ExecRaw(ctx context.Context, c client.Client, workflowID, command string, ...) (json.RawMessage, error)
- func ExecWithRequestID[Spec, State, Res any, Req entity.Command[Res]](ctx context.Context, cl *Client[Spec, State], id entity.ResourceID, ...) (Res, error)
- func ExecWithStart[Spec, State, Res any, Req entity.Command[Res]](ctx context.Context, cl *Client[Spec, State], id entity.ResourceID, spec Spec, ...) (Res, error)
- func Read[Spec, State, Res any, Req entity.Query[Res]](ctx context.Context, cl *Client[Spec, State], id entity.ResourceID, req Req) (Res, error)
- func ReadRaw(ctx context.Context, c client.Client, workflowID, query string, ...) (json.RawMessage, error)
- func SetLabelsRaw(ctx context.Context, c client.Client, workflowID string, ...) error
- type Client
- func (cl *Client[Spec, State]) CreateOrAttach(ctx context.Context, id entity.ResourceID, spec Spec, opts ...StartOption) (client.WorkflowRun, error)
- func (cl *Client[Spec, State]) Delete(ctx context.Context, id entity.ResourceID) error
- func (cl *Client[Spec, State]) Describe(ctx context.Context, id entity.ResourceID) (entity.DescribeOut[Spec, State], error)
- func (cl *Client[Spec, State]) WorkflowID(id entity.ResourceID) string
- type StartOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyRaw ¶
func ApplyRaw(ctx context.Context, c client.Client, kind entity.KindName, id entity.ResourceID, taskQueue string, spec json.RawMessage, labels map[string]string) (string, error)
ApplyRaw declares an entity by WIRE IDENTITY: kind, id and a spec that is only JSON here. This is what a control plane needs to create records of kinds it does not have Go definitions for — the same create-or-attach as the typed path, so declaring twice attaches instead of forking.
The kind's own Init validates the spec: an operator cannot smuggle a shape past the definition, it can only fail to satisfy it.
func DescribeRaw ¶
DescribeRaw reads the built-in describe of any entity: phase, spec, state — as raw JSON.
func Exec ¶
func Exec[Spec, State, Res any, Req entity.Command[Res]](ctx context.Context, cl *Client[Spec, State], id entity.ResourceID, req Req) (Res, error)
Exec sends a command to a running entity as a Temporal Update and waits for its result. The command value IS the request: its type carries the name and the response type, so the call site has no strings and no explicit type parameters. A fresh application-level request id is generated; to retry an operation idempotently, use ExecWithRequestID with the same id — the entity dedups it even across Continue-as-New.
func ExecRaw ¶
func ExecRaw(ctx context.Context, c client.Client, workflowID, command string, payload json.RawMessage, requestID string) (json.RawMessage, error)
ExecRaw sends a command to a running entity by wire identity and returns the raw JSON result. The update's validators still run; the request id deduplicates across retries and Continue-as-New.
func ExecWithRequestID ¶
func ExecWithRequestID[Spec, State, Res any, Req entity.Command[Res]](ctx context.Context, cl *Client[Spec, State], id entity.ResourceID, requestID entity.RequestID, req Req) (Res, error)
ExecWithRequestID is Exec with an explicit request id for deduplication.
func ExecWithStart ¶
func ExecWithStart[Spec, State, Res any, Req entity.Command[Res]](ctx context.Context, cl *Client[Spec, State], id entity.ResourceID, spec Spec, req Req, opts ...StartOption) (Res, error)
ExecWithStart atomically starts the entity if absent (with the given desired spec) AND executes the command — the article's update-with-start: one round trip, no create/attach race.
func Read ¶
func Read[Spec, State, Res any, Req entity.Query[Res]](ctx context.Context, cl *Client[Spec, State], id entity.ResourceID, req Req) (Res, error)
Read runs a read-only query against the entity; the query value is the request, typed like commands. Works even after the entity completed.
Types ¶
type Client ¶
type Client[Spec, State any] struct { // contains filtered or unexported fields }
Client is the caller-side handle for one entity kind. Workflow IDs are deterministic — "kind/{resource-id}" — so at most one open entity exists per resource and callers reconnect instead of creating duplicates.
func Bind ¶
func Bind[Spec, State any](d *entdefine.Definition[Spec, State], c client.Client, taskQueue string) *Client[Spec, State]
Bind creates a client handle for a definition.
func (*Client[Spec, State]) CreateOrAttach ¶
func (cl *Client[Spec, State]) CreateOrAttach(ctx context.Context, id entity.ResourceID, spec Spec, opts ...StartOption) (client.WorkflowRun, error)
CreateOrAttach starts the entity for id with the given desired spec, or attaches to the already-running one. Start options (labels) apply only on actual creation — an existing entity keeps its own.
func (*Client[Spec, State]) Delete ¶
Delete signals the entity to tear itself down: fire-and-forget lifecycle event. The entity drains pending work, runs its finalizer, and completes.
func (*Client[Spec, State]) Describe ¶
func (cl *Client[Spec, State]) Describe(ctx context.Context, id entity.ResourceID) (entity.DescribeOut[Spec, State], error)
Describe queries the entity's current status. Non-blocking; works even after the entity workflow has completed.
func (*Client[Spec, State]) WorkflowID ¶
func (cl *Client[Spec, State]) WorkflowID(id entity.ResourceID) string
WorkflowID derives the deterministic workflow ID for a resource. Never put secrets or PII in resource ids — they end up in workflow IDs and Event History.
type StartOption ¶
type StartOption func(*startConfig)
StartOption configures the entity at creation time (options pattern — the declaration surface for instance metadata like labels).
func WithLabel ¶
func WithLabel(key, value string) StartOption
WithLabel sets one label at creation.
func WithLabels ¶
func WithLabels(labels map[string]string) StartOption
WithLabels merges labels onto the entity at creation.
Source Files