temporalqueue

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 2026 License: MIT Imports: 45 Imported by: 0

Documentation

Overview

Package temporalqueue integrates queue jobs and portable workflows with Temporal, while exposing the resource's actual SDK client and registrations. Its framework-owned workflow names and journal records are versioned protocol.

Index

Constants

This section is empty.

Variables

View Source 
var ErrAcceptanceUnknown = errors.New("Temporal workflow acceptance is unresolved")

ErrAcceptanceUnknown means the returned identity needs reconciliation before any new submission. Calling Dispatch again creates a new identity and can duplicate application effects.

View Source 
var ErrAdapterUnavailable = errors.New("Temporal adapter temporarily unavailable")

ErrAdapterUnavailable marks a temporary key-service or adapter-service outage. Approved adapters return this classification only for availability failures. Conversion and propagation retry it three times per SDK callback; deterministic rejection and panics never enter that recovery loop.

Functions

func Client 

func Client(q *queue.Queue) (client.Client, error)

Client returns the actual SDK client belonging to this queue resource. Applications borrow it and must leave Close to the resource owner.

func NewWithConfig 

func NewWithConfig(cfg Config, opts ...queue.Option) (*queue.Queue, error)

NewWithConfig constructs a Temporal-backed queue without starting workers. @group Constructors

Example: Temporal config constructor 

q, err := temporalqueue.NewWithConfig(temporalqueue.Config{
	DriverBaseConfig:       queueconfig.DriverBaseConfig{DefaultQueue: "reports"},
	ClientOptions:          client.Options{HostPort: "localhost:7233"},
	DefaultActivityTimeout: 30 * time.Second,
	ShutdownTimeout:        15 * time.Second,
}, queue.WithWorkers(4))
if err != nil {
	return
}
defer q.Shutdown(context.Background())
_ = q

func NewWorkflowReplayer 

func NewWorkflowReplayer(q *queue.Queue) (result worker.WorkflowReplayer, err error)

NewWorkflowReplayer creates an SDK replayer with this resource's authoritative serialization policy. Its immutable registration plan is shared with worker startup and must contain deterministic definitions. Finish replays before closing this resource, or use a separate read/replay resource with a retained binding. Raw-history replay is routed through the stable namespace-aware SDK path so protected converters receive the same namespace as the original execution.

func RegistrationFingerprint 

func RegistrationFingerprint(q *queue.Queue) (string, error)

RegistrationFingerprint returns the current native and logical handler catalog digest.

Types

type BoundedContextPropagator 

type BoundedContextPropagator interface {
	workflow.ContextPropagator
	// MaxDecodedBytes bounds total allocation caused by untrusted propagated headers.
	MaxDecodedBytes() int
}

BoundedContextPropagator declares the maximum decoded header expansion enforced by an adapter. Implementations must remain replay-safe in workflow methods and bound their own decoding work.

type BoundedDataConverter 

type BoundedDataConverter interface {
	converter.DataConverter
	// DecodingLimits declares limits enforced inside custom decoding/expansion.
	DecodingLimits() SerializationLimits
	// MaxEncodedOverhead bounds bytes added beyond JSON encoding, including protection metadata.
	MaxEncodedOverhead() int
}

BoundedDataConverter declares the expansion, panic and work contract of a custom converter. A declaration is required in addition to outer byte guards. Implementations must honor their limits in context-specific converter copies.

type ClientBinding 

type ClientBinding struct {
	// contains filtered or unexported fields
}

ClientBinding owns one immutable client policy shared by queue and native SDK calls. Close must follow shutdown of all queues and native callers borrowing Client.

func NewClientBinding 

func NewClientBinding(options client.Options, limits SerializationLimits) (binding *ClientBinding, err error)

NewClientBinding creates a lazy SDK client with bounded conversion and redacted diagnostics. It does not connect or create a namespace during construction.

func (*ClientBinding) Client 

func (b *ClientBinding) Client() client.Client

Client returns the actual SDK client for signals, updates, queries and typed workflows.

func (*ClientBinding) Close 

func (b *ClientBinding) Close(ctx context.Context) error

Close rejects outstanding queue borrowers and joins admitted adapter work. Native SDK callers must be joined by the owner before calling Close.

func (*ClientBinding) Namespace 

func (b *ClientBinding) Namespace() string

Namespace returns the namespace fixed when this binding was constructed.

type Config 

type Config struct {
	queueconfig.DriverBaseConfig
	ClientOptions          client.Options
	Binding                *ClientBinding
	WorkerOptions          worker.Options
	WorkflowTaskQueue      string
	ActivityTaskQueue      string
	WorkflowWorkerOptions  worker.Options
	ActivityWorkerOptions  worker.Options
	Register               func(worker.Registry) error
	DefaultActivityTimeout time.Duration
	ShutdownTimeout        time.Duration
	SerializationLimits    SerializationLimits
}

Config configures one Temporal resource with combined or split worker roles. Native workflow/update interceptors can remain in the SDK's process-wide cache after shutdown. Dependencies captured across SDK workflow yields must remain valid for that cache lifetime; resource-owned application I/O belongs in activities.

type ProtectedDataConverter 

type ProtectedDataConverter interface {
	BoundedDataConverter
	// ValidateProtectedPayload checks the adapter's mandatory protection envelope.
	ValidateProtectedPayload(*common.Payload) error
}

ProtectedDataConverter declares authenticated payload protection in addition to bounded decoding. ValidateProtectedPayload must reject plaintext, unknown key IDs, and malformed protection metadata without unbounded decoding or external work. Contextual copies must preserve this policy and reject failed authentication.

type ProtectedFailureConverter 

type ProtectedFailureConverter interface {
	converter.FailureConverter
	// ProtectsFailureDetails confirms the adapter's authenticated encryption policy.
	ProtectsFailureDetails() bool
}

ProtectedFailureConverter declares bounded decoding and protection of native error details. Implementations must encrypt detail payloads and common attributes, enforce a maximum of 16 cause levels and 256 KiB encoded failures, and fail closed when common attributes cannot be decrypted. Serialization-context copies must retain these guarantees. Error type names remain visible retry-policy metadata.

func NewProtectedFailureConverter 

func NewProtectedFailureConverter(dc ProtectedDataConverter) (result ProtectedFailureConverter, err error)

NewProtectedFailureConverter preserves native failure details through an approved protected data converter. Error type names remain visible because Temporal uses them for retry matching.

type Routing 

type Routing struct {
	WorkflowTaskQueue string
	ActivityTaskQueue string
}

Routing describes the resource's resolved native worker roles. Native starters persist ActivityTaskQueue in application workflow input when using split roles.

func WorkerRouting 

func WorkerRouting(q *queue.Queue) (Routing, error)

WorkerRouting returns the actual SDK task queues without silently rewriting native activity options.

type SerializationLimits 

type SerializationLimits struct {
	MaxPayloads     int
	MaxPayloadBytes int
	MaxTotalBytes   int
}

SerializationLimits bound framework payloads before application conversion. Custom adapters must also bound expansion and work inside their own decoding.

func DefaultSerializationLimits 

func DefaultSerializationLimits() SerializationLimits

DefaultSerializationLimits returns conservative limits below service message ceilings.

Source Files

View all Source files

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.