proxy

Documentation

Overview

Package proxy implements cross-domain NACK proxying for retry-endpoint.

When a retry-endpoint serving a downstream multicast domain misses a frame in its cache, it recovers the frame from an upstream retry-endpoint that received the frame directly from the proxy (independent of the bridge that dropped it), re-caches it, and multicast-retransmits it into the downstream domain. The downstream consumer's gap then auto-fills.

Recovery is asynchronous ("cache-warm"): the server returns MISS immediately and enqueues a job here; no NACK worker is held. Because the downstream proxy is not joined to the upstream shard groups, the recovered frame must return by unicast — the upstream endpoint must run with unicast retransmit enabled (proxied NACKs are always served a unicast copy; see the server).

Proxied NACKs carry FlagProxied so an upstream endpoint never re-proxies them, bounding any chain to a single hop.

Index

• Constants
• type Cache
• type Client
  • func New(cfg Config) *Client
  • func (c *Client) Enqueue(hashKey, seq uint64, subtree [32]byte) bool
  • func (c *Client) Start(ctx context.Context)
• type Config
• type Deduper
• type Retransmitter
• type TTLConfig

Constants

const (

	// FlagProxied marks a NACK (Flags byte, offset 7) as recovered on behalf
	// of a downstream domain. An endpoint receiving a NACK with this bit set
	// MUST NOT re-proxy it, bounding the chain to one hop (BRC-126).
	FlagProxied byte = 0x01
)

Types

type Cache

type Cache interface {
	Store(key, value []byte, ttl time.Duration) error
}

Cache is the re-cache surface the proxy needs (subset of cache.Cache).

type Client

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

Client recovers missed frames from upstream retry-endpoints.

func New

func New(cfg Config) *Client

New constructs a Client. Cache and Retrans must be non-nil; Upstreams must be non-empty (validated by config).

func (*Client) Enqueue

func (c *Client) Enqueue(hashKey, seq uint64, subtree [32]byte) bool

Enqueue submits a recovery job for the (hashKey, seq) gap. Non-blocking: if the queue is full the job is dropped and counted. Returns false on drop.

func (*Client) Start

func (c *Client) Start(ctx context.Context)

Start launches the worker pool. Workers run until ctx is cancelled.

type Config

type Config struct {
	Upstreams    []string // upstream NACK targets (host:port)
	Timeout      time.Duration
	MaxEndpoints int // upstream endpoints tried per gap; <=0 = all
	DedupWindow  time.Duration
	Workers      int
	QueueDepth   int
	Dedup        Deduper // may be nil (no cross-instance in-flight dedup)
	Cache        Cache
	Retrans      Retransmitter
	TTLs         TTLConfig
	Rec          *metrics.Recorder
}

Config holds the proxy client's dependencies and tuning.

type Deduper

type Deduper interface {
	SetNX(key, value []byte, ttl time.Duration) (bool, error)
}

Deduper is the cross-instance in-flight-claim surface (subset of cache.Deduper).

type Retransmitter

type Retransmitter interface {
	Retransmit(raw []byte, txID [32]byte) error
}

Retransmitter multicasts a recovered frame into the downstream domain.

type TTLConfig

type TTLConfig struct {
	Tx      time.Duration
	Block   time.Duration
	Subtree time.Duration
	Anchor  time.Duration
}

TTLConfig mirrors the per-FrameVer cache TTLs used by the ingress worker so recovered frames are re-cached with the same lifetime as freshly received ones.