temporalpayload

package
v0.0.0-...-61148be Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package temporalpayload provides the local, size-aware Temporal payload codec chain.

A Codec always starts with Temporal's normal serialization. It retains that representation unless a zstd wrapper is strictly smaller, then retains that representation unless an immutable content-addressed blob reference is strictly smaller. Runtime clients and workers use Codec.DataConverter locally. NewUIHandler exposes the identical codec only for an authorized Temporal UI inspection endpoint; it is never on a worker's normal path.

The package provides integrity and compatibility, not encryption. Callers provide the BlobStore implementation appropriate to their object store and must declare its endpoint, credentials, prefix, lifecycle, and retention in their deployment configuration.

Index

Constants

View Source 
const (
	// EncodingZstd identifies a v1 zstd-wrapped Temporal payload.
	EncodingZstd = "binary/zstd"
	// EncodingRemote identifies a v1 immutable blob-reference Temporal payload.
	EncodingRemote = "binary/remote-payload"
)

Variables

View Source 
var (
	// ErrUnsupportedVersion reports a payload written by a codec version outside the declared compatibility window.
	ErrUnsupportedVersion = errors.New("unsupported temporal payload codec version")
	// ErrInvalidPayload reports malformed codec metadata, references, or nested payload bytes.
	ErrInvalidPayload = errors.New("invalid temporal payload codec payload")
)
View Source 
var (
	// ErrBlobNotFound reports a payload reference whose immutable content is absent.
	ErrBlobNotFound = errors.New("temporal payload blob not found")
	// ErrBlobIntegrity reports a payload reference whose content does not match its digest or size.
	ErrBlobIntegrity = errors.New("temporal payload blob integrity check failed")
	// ErrBlobTooLarge reports a blob which exceeds the codec's configured finite bound.
	ErrBlobTooLarge = errors.New("temporal payload blob exceeds configured size limit")
)

Functions

func NewUIHandler 

func NewUIHandler(codec *Codec, options ...UIHandlerOption) (http.Handler, error)

NewUIHandler creates the authenticated HTTP adapter used only by Temporal UI inspection.

Types

type AuthorizationDecision 

type AuthorizationDecision struct {
	Authenticated bool
	Allowed       bool
}

AuthorizationDecision reports the result of an authentication and namespace-authorization check.

It deliberately contains no credential, header, token, or principal value so the payload package has nothing sensitive to log or retain.

type BlobKey 

type BlobKey string

BlobKey identifies an immutable object owned by the payload codec.

Codec creates keys from a configured prefix and the SHA-256 digest of stored bytes. BlobStore implementations must treat a key as opaque and must not infer an object-store endpoint from it.

func (BlobKey) String 

func (key BlobKey) String() string

String returns the storage-neutral canonical key text.

type BlobObject 

type BlobObject struct {
	Key       BlobKey
	CreatedAt time.Time
}

BlobObject is immutable blob metadata exposed only to an explicit retention worker.

type BlobStore 

type BlobStore interface {
	Put(context.Context, BlobKey, []byte) error
	Get(context.Context, BlobKey, int) ([]byte, error)
}

BlobStore stores immutable payload content under a codec-owned BlobKey.

Put must be idempotent for equal bytes and must reject a different value at an existing key. Get must return no more than maxBytes; this lets a store enforce the codec's bounded read policy before allocating unbounded content.

type Codec 

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

Codec implements Temporal's PayloadCodec using a local zstd/blob transformation chain.

func NewCodec 

func NewCodec(store BlobStore, options ...Option) (*Codec, error)

NewCodec creates a local payload codec with explicit immutable blob storage.

func (*Codec) CheckCompatibility 

func (codec *Codec) CheckCompatibility(ctx context.Context) error

CheckCompatibility verifies retained v1 inline, zstd, and remote payload vectors before accepting work.

func (*Codec) DataConverter 

func (codec *Codec) DataConverter() converter.DataConverter

DataConverter returns the local Temporal DataConverter that owns payload selection transparently.

func (*Codec) Decode 

func (codec *Codec) Decode(payloads []*commonpb.Payload) ([]*commonpb.Payload, error)

Decode restores every representation within the declared v1 compatibility window.

func (*Codec) Encode 

func (codec *Codec) Encode(payloads []*commonpb.Payload) ([]*commonpb.Payload, error)

Encode transforms each ordinary Temporal payload into its strictly smallest supported representation.

type GarbageCollector 

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

GarbageCollector computes and applies only explicitly authorized, age-bounded deletion.

func NewGarbageCollector 

func NewGarbageCollector(coordinator RetentionCoordinator, prefix string, minimumAge time.Duration) (*GarbageCollector, error)

NewGarbageCollector creates the retention-only deletion coordinator.

func (*GarbageCollector) Collect 

func (collector *GarbageCollector) Collect(ctx context.Context, evaluatedAt time.Time) ([]BlobKey, error)

Collect deletes only objects older than the supplied evaluation time minus the configured minimum age through RetentionCoordinator.

type MemoryBlobStore 

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

MemoryBlobStore is a concurrent in-memory BlobStore for tests and local deterministic consumers. It is not durable storage.

func NewMemoryBlobStore 

func NewMemoryBlobStore() *MemoryBlobStore

NewMemoryBlobStore creates a concurrent in-memory immutable BlobStore.

func (*MemoryBlobStore) Count 

func (store *MemoryBlobStore) Count() int

Count returns the number of stored objects. It is intended for deterministic tests.

func (*MemoryBlobStore) Delete 

func (store *MemoryBlobStore) Delete(ctx context.Context, key BlobKey) error

Delete removes key from the deterministic test store. Production object stores must make deletion an explicit retention/GC operation rather than a normal codec concern.

func (*MemoryBlobStore) Get 

func (store *MemoryBlobStore) Get(ctx context.Context, key BlobKey, maxBytes int) ([]byte, error)

Get retrieves an immutable value while enforcing maxBytes before cloning it.

func (*MemoryBlobStore) Put 

func (store *MemoryBlobStore) Put(ctx context.Context, key BlobKey, value []byte) error

Put stores bytes exactly once for key.

type Observation 

type Observation struct {
	Operation       string
	Selection       string
	InputSizeBytes  int
	OutputSizeBytes int
}

Observation is a bounded payload codec observation suitable for a metrics adapter.

type Observer 

type Observer interface {
	ObservePayload(Observation)
}

Observer records bounded codec observations without receiving payload bytes or blob keys.

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option configures a Codec. It is sealed so codecs cannot receive unchecked configuration.

func WithBlobPrefix 

func WithBlobPrefix(prefix string) Option

WithBlobPrefix configures the explicit object-store prefix that owns this codec's content-addressed keys.

func WithIOTimeout 

func WithIOTimeout(timeout time.Duration) Option

WithIOTimeout configures the finite background I/O bound required by Temporal's payload codec API.

func WithMaximumBlobBytes 

func WithMaximumBlobBytes(maximum int) Option

WithMaximumBlobBytes configures the maximum immutable payload object the codec will write or read.

func WithObserver 

func WithObserver(observer Observer) Option

WithObserver configures a bounded metrics observer for codec outcomes.

type RetentionCoordinator 

type RetentionCoordinator interface {
	List(context.Context, string) ([]BlobObject, error)
	FenceAndDeleteUnreferenced(context.Context, BlobKey, time.Time, time.Time) (deleted bool, err error)
}

RetentionCoordinator owns both the authoritative reference fence and deletion protocol.

FenceAndDeleteUnreferenced must atomically fence new authoritative reference creation, prove that the object has no authoritative reference, and condition deletion on the listed object creation identity. When an external object store cannot be deleted under that durable fence, it returns deleted=false and leaves a durable tombstone/reconciliation record rather than guessing. Codec deliberately does not implement or receive this interface.

type UIHandlerOption 

type UIHandlerOption interface {
	// contains filtered or unexported methods
}

UIHandlerOption configures the authenticated Temporal UI inspection handler.

func WithTemporalUINamespaces 

func WithTemporalUINamespaces(namespaces ...string) UIHandlerOption

WithTemporalUINamespaces limits the handler to the declared Temporal namespaces.

func WithTemporalUIOrigins 

func WithTemporalUIOrigins(origins ...string) UIHandlerOption

WithTemporalUIOrigins limits browser access to the declared Temporal UI origins.

func WithTemporalUIRequestAuthorizer 

func WithTemporalUIRequestAuthorizer(authorizer UIRequestAuthorizer) UIHandlerOption

WithTemporalUIRequestAuthorizer requires trusted authentication and namespace authorization.

type UIRequestAuthorizer 

type UIRequestAuthorizer interface {
	AuthorizeTemporalPayloadUI(request *http.Request, namespace string) (AuthorizationDecision, error)
}

UIRequestAuthorizer authenticates a Temporal UI request and authorizes its requested namespace. Implementations must establish identity from a trusted boundary (for example verified OIDC middleware or an mTLS peer), rather than treating X-Namespace, Origin, or a network location as authentication.

The handler passes the full request so an implementation can read trusted authentication context installed by its enclosing middleware. It must not retain or log request credentials.

type UIRequestAuthorizerFunc 

type UIRequestAuthorizerFunc func(request *http.Request, namespace string) (AuthorizationDecision, error)

UIRequestAuthorizerFunc adapts a function into a UIRequestAuthorizer.

func (UIRequestAuthorizerFunc) AuthorizeTemporalPayloadUI 

func (authorizer UIRequestAuthorizerFunc) AuthorizeTemporalPayloadUI(request *http.Request, namespace string) (AuthorizationDecision, error)

AuthorizeTemporalPayloadUI calls authorizer.

Source Files

View all Source files

Directories

Path Synopsis
Package s3 adapts an S3-compatible object store to temporalpayload.BlobStore.
 Package s3 adapts an S3-compatible object store to temporalpayload.BlobStore.

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.