grpcx

Documentation

Overview

Package grpcx holds the transport behaviour shared by the Photon runtime gRPC clients (iMessage, WhatsApp Business, Slack): channel defaults, bearer/metadata auth, idempotency keys, and the x-retryable retry contract. It mirrors the middleware stack of the official spectrum-ts SDK.

Index

• Constants
• func BaseDialOptions(insecureConn bool) []grpc.DialOption
• func BearerAuthStream(token TokenFunc) grpc.StreamClientInterceptor
• func BearerAuthUnary(token TokenFunc) grpc.UnaryClientInterceptor
• func IdempotencyUnary(mutating map[string]bool) grpc.UnaryClientInterceptor
• func MetadataStream(pairs MetadataFunc) grpc.StreamClientInterceptor
• func MetadataUnary(pairs MetadataFunc) grpc.UnaryClientInterceptor
• func RetryUnary(maxAttempts int, initialDelay, maxDelay time.Duration) grpc.UnaryClientInterceptor
• type MetadataFunc
• type TokenFunc
  • func StaticToken(token string) TokenFunc

Constants

const (
	MaxMessageBytes  = 100 * 1024 * 1024
	KeepaliveTime    = 30 * time.Second
	KeepaliveTimeout = 20 * time.Second
)

Channel defaults, matching the official SDK's grpc-js options.

const (
	RetryMaxAttempts  = 4
	RetryInitialDelay = 200 * time.Millisecond
	RetryMaxDelay     = 5 * time.Second
)

Retry defaults, matching the official SDK.

Functions

func BaseDialOptions

func BaseDialOptions(insecureConn bool) []grpc.DialOption

BaseDialOptions returns the channel configuration every Photon runtime connection uses: TLS (or plaintext when insecureConn), keepalive pings that survive idle periods, and 100 MiB message caps sized for attachment transfers.

func BearerAuthStream

func BearerAuthStream(token TokenFunc) grpc.StreamClientInterceptor

BearerAuthStream stamps `authorization: Bearer <token>` on every stream open.

func BearerAuthUnary

func BearerAuthUnary(token TokenFunc) grpc.UnaryClientInterceptor

BearerAuthUnary stamps `authorization: Bearer <token>` on every unary call.

func IdempotencyUnary

func IdempotencyUnary(mutating map[string]bool) grpc.UnaryClientInterceptor

IdempotencyUnary stamps a fresh `x-idempotency-key` UUID on calls to the methods in mutating. The key is applied outside the retry interceptor in the chain, so every retry of one logical call reuses the same key — that is what lets the server dedupe replays.

func MetadataStream

func MetadataStream(pairs MetadataFunc) grpc.StreamClientInterceptor

MetadataStream is MetadataUnary for streams.

func MetadataUnary

func MetadataUnary(pairs MetadataFunc) grpc.UnaryClientInterceptor

MetadataUnary stamps arbitrary metadata pairs on every unary call. Used by platforms whose auth is not a bearer header (WhatsApp Business stamps access_token/phone_number_id/app_secret).

func RetryUnary

func RetryUnary(maxAttempts int, initialDelay, maxDelay time.Duration) grpc.UnaryClientInterceptor

RetryUnary retries unary calls the server has explicitly marked replayable via `x-retryable: true` trailing metadata — the server's proof that the request never produced a side effect. Delays follow full-jitter exponential backoff: uniform in [0, min(initial·2ⁿ, max)). Streams are never retried; reconnect loops own that.

Types

type MetadataFunc

type MetadataFunc func(ctx context.Context) ([]string, error)

MetadataFunc supplies per-call metadata pairs (key, value, key, value, ...).

type TokenFunc

type TokenFunc func(ctx context.Context) (string, error)

TokenFunc supplies the current bearer token for a call. It is invoked per attempt, so refreshed tokens are picked up without reconnecting.

func StaticToken

func StaticToken(token string) TokenFunc

StaticToken adapts a fixed token string to a TokenFunc.