nats

package
v0.65.9 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source
const (
	WORKSPACE_PROVISION_JOBS_BUCKET = "workspace-provision-jobs"

	// LOCKED_USERS_BUCKET holds per-user account lock state, keyed by
	// username. See UserLockState (userlock.go) for the value type stored in
	// it and the producer/consumer contract between api-server and ssh-proxy.
	LOCKED_USERS_BUCKET = "locked-users"

	// PASSWORD_LOCKOUT_BUCKET holds per-username password brute-force
	// tracking state, keyed by username. See PasswordLockoutState
	// (passwordlockout.go) for the value type stored in it. Unlike
	// LOCKED_USERS_BUCKET, identity is the sole producer and consumer: it
	// reads and writes this bucket directly inside AuthUserPassword, so the
	// lockout applies consistently no matter which caller (ssh-proxy,
	// api-server, or any other gRPC client) invoked it.
	PASSWORD_LOCKOUT_BUCKET = "password-lockouts"

	// PASSWORD_RESET_TOKEN_BUCKET holds single-use password-reset tokens,
	// keyed by hex(sha256(token)), value = username. Identity is the sole
	// producer and consumer. TTL bounds how long an issued reset link stays
	// valid; ConfirmPasswordReset deletes a token immediately on successful
	// use, but the bucket-wide TTL also cleans up abandoned tokens.
	PASSWORD_RESET_TOKEN_BUCKET = "password-reset-tokens"

	// PASSWORD_RESET_COOLDOWN_BUCKET holds a per-username marker created by
	// RequestPasswordReset to throttle repeat requests. Keyed by username,
	// empty value. A separate bucket from PASSWORD_RESET_TOKEN_BUCKET
	// because JetStream KV TTL is bucket-wide and the two need very
	// different lifetimes (short cooldown vs. longer token validity).
	PASSWORD_RESET_COOLDOWN_BUCKET = "password-reset-cooldown"

	// RECORDING_OVERRIDES_BUCKET holds per-workspace recording overrides,
	// keyed by workspace name. See RecordingOverride (recordingoverride.go)
	// for the value type and the producer/consumer contract between
	// api-server and ssh-proxy. No TTL: an override lasts until deleted.
	RECORDING_OVERRIDES_BUCKET = "recording-overrides"

	// THREAT_DETECTION_BUCKET holds per-workspace threat detection decisions,
	// keyed by workspace name: the threat:detect policy result and the
	// detection override. See ThreatDetection (threatdetection.go) for the
	// value type and the producer/consumer contract between the provisioner,
	// api-server and worktrace. No TTL: an entry lasts until its workspace is
	// deleted.
	THREAT_DETECTION_BUCKET = "threat-detection"
)
View Source
const (
	// THREATS_STREAM is the JetStream stream that carries threats reported by
	// worktrace detectors. The worktrace controller creates it and consumes
	// it; detectors only publish. See models.ThreatEvent for the payload.
	THREATS_STREAM = "WORKTRACE_THREATS"

	// THREATS_SUBJECT_PREFIX prefixes every threat subject; the stream binds
	// THREATS_SUBJECT_PREFIX + ".>".
	THREATS_SUBJECT_PREFIX = "worktrace.threats"

	// THREATS_CONSUMER is the durable consumer the controller replicas share,
	// so each threat is handled by exactly one replica.
	THREATS_CONSUMER = "worktrace-controller"
)
View Source
const NoBucketTTL time.Duration = -1

NoBucketTTL as BucketOptions.BucketTTL creates a bucket whose entries never expire. A zero BucketTTL means the default (24h), not "no TTL".

Variables

View Source
var ErrDiscard = errors.New("discard message")

ErrDiscard, wrapped in a handler's error, makes the subscriber terminate the message instead of redelivering it (e.g. a payload that can never be parsed).

Functions

func Fetch

func Fetch[T any](ctx context.Context, cache *JetStreamKV, key string,
	fetch func(context.Context) (T, error),
) (T, error)

Fetch retrieves a value from cache by key. On miss, calls fetch(), caches result with TTL, and returns it.

func NatsOptionsFromConfig

func NatsOptionsFromConfig(name string, cfg NATSClientConfig) []nats.Option

func ResolveDetectObligation added in v0.63.2

func ResolveDetectObligation(policy authz.DetectObligation, policyFound bool, override *ThreatDetectionOverride) (authz.DetectObligation, bool)

ResolveDetectObligation applies a workspace's detection override to the threat:detect policy result. policy and policyFound are what authz.ParseDetectObligation returned; override is nil when the workspace has none. An override replaces the policy result entirely, so the result is then always found, even for "none".

func ResolveRecordObligation added in v0.62.8

func ResolveRecordObligation(policy authz.RecordObligation, policyFound bool, override *RecordingOverride) (authz.RecordObligation, bool)

ResolveRecordObligation applies a workspace's recording override to the session:record policy result. policy and policyFound are what authz.ParseRecordObligation returned; override is nil when the workspace has none. An override replaces the policy result entirely, so the result is then always found, even for "none".

func ThreatSubject added in v0.63.1

func ThreatSubject(namespace, workspace, rule string) string

ThreatSubject builds the subject a threat is published on:

worktrace.threats.<namespace>.<workspace>.<rule>

so consumers can filter by namespace, workspace or rule without parsing the payload. Empty parts become "_", and characters that are not allowed in a NATS subject token (. * > whitespace) are replaced with "_".

func UpdateThreatDetection added in v0.63.2

func UpdateThreatDetection(kv *JetStreamKV, workspace string, mutate func(*ThreatDetection)) error

UpdateThreatDetection changes the workspace's entry with compare-and-set, so the provisioner (Policy) and api-server (Override) never overwrite each other's field. mutate receives the current value (zero when there is none) and changes it in place; an entry left with neither field is deleted.

Types

type BucketOptions

type BucketOptions struct {
	Bucket    string           `yaml:"bucket" json:"bucket"`
	BucketTTL time.Duration    `yaml:"bucketTTL" json:"bucketTTL"`
	History   uint8            `yaml:"history" json:"history"`
	Storage   nats.StorageType `yaml:"storage" json:"storage"`
	// Replicas is the number of server replicas of the bucket. Zero means
	// the default: 3 on a NATS cluster, 1 on a single server (see
	// defaultReplicas). It must not exceed the size of the cluster.
	Replicas int `yaml:"replicas" json:"replicas"`
}

BucketOptions holds options for the JetStream cache bucket.

func ThreatDetectionBucketOptions added in v0.63.2

func ThreatDetectionBucketOptions(replicas int) BucketOptions

ThreatDetectionBucketOptions are the options THREAT_DETECTION_BUCKET is created with. Only the worktrace controller creates the bucket; producers (provisioner, api-server) open it by name with NATSClient.OpenKV and treat a missing bucket as worktrace not being installed.

type JSLock

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

JSLock is a guard returned by AcquireLock. Call Release() when done.

func (*JSLock) Release

func (l *JSLock) Release() error

Release attempts to release the lock by deleting its key, guarded by a CAS revision check. It only releases if we still own the lock; otherwise it is a no-op.

The key is deleted rather than CAS-updated to an empty/zeroed envelope: AcquireLock's takeover check only reclaims an existing key once its ExpireAt has passed (cur.ExpireAt > 0 && now >= cur.ExpireAt), and a zeroed envelope has ExpireAt == 0, which never satisfies that condition. Leaving such an envelope behind would make the key permanently unacquirable — every future AcquireLock on it would fail immediately with nats.ErrKeyExists, even with no other holder in sight.

type JetStreamKV

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

JetStreamKV is a cache client backed by NATS JetStream KV store.

func (*JetStreamKV) AcquireLock

func (c *JetStreamKV) AcquireLock(key string, ttl time.Duration) (*JSLock, error)

AcquireLock attempts to acquire a lock at key with TTL. Returns nats.ErrKeyExists if the lock is already held and not expired. On success returns a guard; call guard.Release() to release. Implemented using KV Create() and CAS Update() when taking over expired locks.

func (*JetStreamKV) Create

func (c *JetStreamKV) Create(key string, value []byte) (uint64, error)

Create stores raw bytes at key only if missing. Returns nats.ErrKeyExists if already present.

func (*JetStreamKV) Delete

func (c *JetStreamKV) Delete(key string) error

Delete removes a key. Returns nats.ErrKeyNotFound if missing.

func (*JetStreamKV) Get

func (c *JetStreamKV) Get(key string) (nats.KeyValueEntry, error)

Get retrieves raw bytes at key.

func (*JetStreamKV) Set

func (c *JetStreamKV) Set(key string, value []byte) (uint64, error)

Set stores raw bytes at key.

func (*JetStreamKV) Update

func (c *JetStreamKV) Update(key string, value []byte, revision uint64) (uint64, error)

func (*JetStreamKV) WatchAll added in v0.63.2

func (c *JetStreamKV) WatchAll(opts ...nats.WatchOpt) (nats.KeyWatcher, error)

WatchAll watches every key of the bucket. The watcher first delivers the current value of each key, then a nil entry marking the end of that initial snapshot, then every later change (deletes as KeyValueDelete or KeyValuePurge operations). Stop it when done.

type KVEvent

type KVEvent struct {
	Bucket string
	Key    string
	Op     string
	Value  []byte
	Seq    uint64
	Time   time.Time
	Msg    *nats.Msg
}

KVEvent represents a single key-value event.

type KVSubscriber

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

KVSubscriber is a NATS JetStream KV bucket subscriber.

func (*KVSubscriber) StartPull

func (s *KVSubscriber) StartPull(ctx context.Context, handler func(context.Context, *KVEvent) error) error

StartPull runs the pull loop until ctx is canceled. handler must be idempotent; Ack happens only if handler returns nil.

func (*KVSubscriber) Stop

func (s *KVSubscriber) Stop() error

Stop unsubscribes from the KV bucket.

type KVSubscriberOptions

type KVSubscriberOptions struct {
	DeliverAll     bool // true to replay all from start; false to get new only
	AckWait        time.Duration
	MaxAckPending  int
	FetchBatchSize int
	FetchMaxWait   time.Duration
	// InactiveThreshold is how long the server keeps the consumer after the
	// last client activity before deleting it, so consumers of dead clients
	// do not accumulate. Defaults to defaultInactiveThreshold.
	InactiveThreshold time.Duration
}

KVSubscriberOptions holds options for the KVSubscriber.

type Lock

type Lock interface {
	Release() error
}

type NATSClient

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

func NewNATSClient

func NewNATSClient(cfg NATSClientConfig) (*NATSClient, error)

func (*NATSClient) Close

func (c *NATSClient) Close()

func (*NATSClient) DeleteStream added in v0.63.1

func (c *NATSClient) DeleteStream(name string) error

DeleteStream removes a stream and its messages. Services do not normally call it; it exists for tests and tooling.

func (*NATSClient) EnsureStream added in v0.63.1

func (c *NATSClient) EnsureStream(opts StreamOptions) error

EnsureStream creates the stream, or updates it to the given options if it already exists. It is idempotent and safe to call from several replicas.

func (*NATSClient) NewKV

func (c *NATSClient) NewKV(bucketOpts BucketOptions) (*JetStreamKV, error)

func (*NATSClient) NewKVSubscriber

func (c *NATSClient) NewKVSubscriber(bucket, durable string,
	o KVSubscriberOptions) (*KVSubscriber, error)

NewKVSubscriber connects to NATS using your config and prepares a subscriber. Close() will drain/close the connection (since this constructor owns it).

func (*NATSClient) NewStreamPublisher added in v0.63.1

func (c *NATSClient) NewStreamPublisher(opts StreamPublisherOptions) (*StreamPublisher, error)

NewStreamPublisher creates a publisher on the client's connection.

func (*NATSClient) NewStreamSubscriber added in v0.63.1

func (c *NATSClient) NewStreamSubscriber(stream, durable string, o StreamSubscriberOptions) (*StreamSubscriber, error)

NewStreamSubscriber prepares a subscriber on the stream's durable consumer.

func (*NATSClient) OpenKV added in v0.63.2

func (c *NATSClient) OpenKV(bucket string) (*JetStreamKV, error)

OpenKV opens an existing bucket, for consumers that must not create it themselves. It returns nats.ErrBucketNotFound while the bucket is missing.

func (*NATSClient) ServerVersion added in v0.49.0

func (c *NATSClient) ServerVersion() string

ServerVersion returns the version of the NATS server this client is currently connected to, as advertised in the server's INFO protocol (e.g. "2.10.7"). It returns "" when the client is not connected.

func (*NATSClient) SubscribeKVChanges added in v0.63.6

func (c *NATSClient) SubscribeKVChanges(bucket string, handler func(*KVEvent)) (*nats.Subscription, error)

SubscribeKVChanges delivers every write to bucket as it happens, using a plain core NATS subscription on the bucket's subjects ("$KV.<bucket>.>"). Unlike NewKVSubscriber it creates no JetStream consumer, so there is no server-side state to leak when the process exits; the server drops the interest with the connection. The trade-off is no replay: writes made while disconnected are missed. Delete and purge events carry an empty Value and the operation in Op. The handler runs on one goroutine per subscription. Unsubscribe the returned subscription when done.

type NATSClientConfig

type NATSClientConfig struct {
	Enabled       bool   `yaml:"enabled" json:"enabled"`
	URL           string `yaml:"url" json:"url"`
	Username      string `yaml:"username" json:"username"`
	Password      string `yaml:"password" json:"password"`
	Token         string `yaml:"token"    json:"token"`
	MaxReconnects int    `yaml:"maxReconnects" json:"maxReconnects"`
	// RetryOnFailedConnect makes the initial connect return immediately and
	// keep retrying in the background when the server is unreachable, instead
	// of failing. For clients that must start without NATS.
	RetryOnFailedConnect bool          `yaml:"retryOnFailedConnect" json:"retryOnFailedConnect"`
	ReconnectWait        time.Duration `yaml:"reconnectWait" json:"reconnectWait"`
}

NATSClientConfig holds NATS connection.

type PasswordLockoutState added in v0.34.3

type PasswordLockoutState struct {
	// FailedAttempts is the number of consecutive failed password attempts
	// since the last success or lockout expiry.
	FailedAttempts int `json:"failedAttempts,omitempty"`

	// LockedUntil is the unix time (seconds) the account remains locked
	// until. Zero means not currently locked.
	LockedUntil int64 `json:"lockedUntil,omitempty"`
}

PasswordLockoutState is the JSON value stored in PASSWORD_LOCKOUT_BUCKET for a username, tracking password-authentication failures.

identity is the sole producer and consumer: AuthUserPassword reads and writes this bucket directly on every call, regardless of which caller (ssh-proxy, api-server, or any other gRPC client) invoked it, so the lockout is enforced consistently no matter which auth surface is used. This is distinct from UserLockState/LOCKED_USERS_BUCKET, which tracks an administrative lock set by api-server and observed by ssh-proxy.

type RecordingOverride added in v0.62.8

type RecordingOverride struct {
	// Record is the replacement "record" obligation value: a comma-separated
	// list of authz.ObligationRecord* tokens, or "none" to disable recording.
	// Producers validate it with authz.ValidateRecordObligation.
	Record string `json:"record"`

	// SetBy is the username that set the override, for auditing.
	SetBy string `json:"setBy,omitempty"`

	// SetAt is the unix time (seconds) the override was set.
	SetAt int64 `json:"setAt,omitempty"`
}

RecordingOverride is the JSON value stored in RECORDING_OVERRIDES_BUCKET for a workspace name. It replaces the "record" obligation the policy engine returns for session:record, for every session to that workspace.

api-server is the sole producer: it writes and deletes entries through its /workspaces/{name}/recording-override endpoints, guarded by session:recording:override.

api-server (webshell) and ssh-proxy (SSH sessions) are consumers: each looks up the workspace's entry when a session starts, after evaluating session:record, and passes both to ResolveRecordObligation. A session already running keeps the recording it started with.

type StreamMessage added in v0.63.1

type StreamMessage struct {
	Subject string
	Data    []byte
	// Seq is the stream sequence; Time is when the stream stored the message.
	Seq  uint64
	Time time.Time
	// Deliveries is how many times this message was delivered (1 on first).
	Deliveries uint64
}

StreamMessage is a message delivered by a StreamSubscriber.

type StreamOptions added in v0.63.1

type StreamOptions struct {
	Name     string
	Subjects []string
	// MaxAge is how long messages are kept. Default 24h.
	MaxAge time.Duration
	// MaxBytes caps the stream size; the oldest messages are discarded first.
	// Default 1 GiB.
	MaxBytes int64
	// Replicas is the number of server replicas; it must not exceed the size
	// of the NATS cluster. Default 3 on a cluster, 1 on a single server.
	Replicas int
	// Duplicates is the window in which a repeated message ID is dropped.
	// Default 5m.
	Duplicates time.Duration
}

StreamOptions describes a JetStream stream for EnsureStream.

type StreamPublisher added in v0.63.1

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

StreamPublisher publishes to JetStream without blocking the caller: a message is handed to the client, acknowledged asynchronously, and republished with backoff if that fails. Delivery is at-least-once; the message ID makes JetStream drop duplicates within the stream's duplicate window.

func (*StreamPublisher) Flush added in v0.63.1

func (p *StreamPublisher) Flush(ctx context.Context) error

Flush waits until all in-flight messages are acknowledged or ctx ends.

func (*StreamPublisher) Publish added in v0.63.1

func (p *StreamPublisher) Publish(subject string, data []byte, msgID string) error

Publish queues data on subject. msgID, if set, is the deduplication ID. It returns an error only if the message could not even be handed to the client (too many unacknowledged messages); later failures are retried.

func (*StreamPublisher) Stats added in v0.63.1

func (p *StreamPublisher) Stats() (retried, dropped uint64)

Stats reports messages republished after a failure and messages dropped.

type StreamPublisherOptions added in v0.63.1

type StreamPublisherOptions struct {
	// MaxPending bounds unacknowledged messages in flight. Default 4096.
	MaxPending int
	// MaxRetries is how often a message that failed (no ack, no stream yet,
	// server down) is republished before it is dropped. Default 10.
	MaxRetries int
	// MaxBackoff caps the delay between retries, which start at 1s and double.
	// Default 30s.
	MaxBackoff time.Duration
	// MaxRetryQueue bounds messages waiting for a retry; beyond it, failed
	// messages are dropped. Default 10000.
	MaxRetryQueue int
}

StreamPublisherOptions tunes a StreamPublisher.

type StreamSubscriber added in v0.63.1

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

StreamSubscriber pulls messages from a durable consumer. Subscribers that share a durable name share the work: each message goes to one of them.

func (*StreamSubscriber) Run added in v0.63.1

func (s *StreamSubscriber) Run(ctx context.Context, handler func(context.Context, *StreamMessage) error) error

Run delivers messages to handler until ctx is cancelled. A message is acknowledged when handler returns nil, terminated when the error wraps ErrDiscard, and redelivered shortly after for any other error (up to MaxDeliver times). If the stream or consumer disappears, or the server is unreachable, Run re-establishes the subscription instead of returning.

type StreamSubscriberOptions added in v0.63.1

type StreamSubscriberOptions struct {
	// FilterSubject restricts the consumer to matching subjects; empty means
	// the whole stream.
	FilterSubject string
	// DeliverAll starts a new consumer at the oldest stored message instead of
	// only new ones. Has no effect on an existing durable consumer.
	DeliverAll bool
	// AckWait is how long a handler may take before redelivery. Default 30s.
	AckWait time.Duration
	// MaxDeliver bounds redeliveries of a failing message. Default 10.
	MaxDeliver int
	// MaxAckPending bounds unacknowledged messages. Default 1024.
	MaxAckPending  int
	FetchBatchSize int
	FetchMaxWait   time.Duration
}

StreamSubscriberOptions tunes a StreamSubscriber.

type ThreatDetection added in v0.63.2

type ThreatDetection struct {
	// Policy is the threat:detect result; nil when the policy has not been
	// evaluated for the workspace (yet).
	Policy *ThreatDetectionPolicy `json:"policy,omitempty"`

	// Override replaces Policy while set.
	Override *ThreatDetectionOverride `json:"override,omitempty"`
}

ThreatDetection is the JSON value stored in THREAT_DETECTION_BUCKET for a workspace name: which attack categories worktrace watches on the workspace. It keeps the policy result and the override apart, so clearing an override falls back to the policy result without evaluating the policy again.

Producers, each writing only its own field with UpdateThreatDetection:

  • the provisioner evaluates threat:detect when it provisions a workspace and sets Policy; it deletes the entry when it deletes the workspace.
  • api-server sets and clears Override through its /workspaces/{name}/detection-override endpoints, guarded by threat:detection:override.

Consumer: every worktrace detector watches the bucket and applies Resolve to each workspace's events as they arrive, so a change applies at once to a running workspace. A workspace without an entry gets the detector's configured default.

func ParseThreatDetection added in v0.63.2

func ParseThreatDetection(value []byte) (*ThreatDetection, error)

ParseThreatDetection decodes a THREAT_DETECTION_BUCKET value.

func (*ThreatDetection) Resolve added in v0.63.2

func (d *ThreatDetection) Resolve() (ob authz.DetectObligation, found bool)

Resolve returns the workspace's effective detect obligation: the override when one is set, else the policy result. found is false when neither decides, and the consumer then applies its default.

type ThreatDetectionOverride added in v0.63.2

type ThreatDetectionOverride struct {
	// Detect is the replacement "detect" obligation value: "none", "all" or
	// comma-separated categories. Producers validate it with
	// authz.ValidateDetectObligation.
	Detect string `json:"detect"`

	// SetBy is the username that set the override, for auditing.
	SetBy string `json:"setBy,omitempty"`

	// SetAt is the unix time (seconds) the override was set.
	SetAt int64 `json:"setAt,omitempty"`
}

ThreatDetectionOverride is a stored detection override.

type ThreatDetectionPolicy added in v0.63.2

type ThreatDetectionPolicy struct {
	// Detect is the "detect" obligation value; empty when the policy returned
	// none, which leaves the workspace to the detector's default.
	Detect string `json:"detect,omitempty"`

	// EvaluatedFor is the subject the policy was evaluated as.
	EvaluatedFor string `json:"evaluatedFor,omitempty"`

	// EvaluatedAt is the unix time (seconds) of the evaluation.
	EvaluatedAt int64 `json:"evaluatedAt,omitempty"`
}

ThreatDetectionPolicy is a stored threat:detect policy result.

type UserLockState added in v0.34.3

type UserLockState struct {
	// Locked is whether the account is currently locked. Consumers should
	// treat any request/connection for this username as denied while true.
	Locked bool `json:"locked,omitempty"`

	// SessionsInvalidBefore is the unix time (seconds) of the most recent
	// lock. Unlike Locked, it survives the account being unlocked again, so
	// api-server can keep rejecting a web session that predates the lock
	// even after unlock — forcing a fresh login rather than silently
	// resuming. ssh-proxy has no equivalent persistent session concept and
	// can ignore this field.
	SessionsInvalidBefore int64 `json:"sessionsInvalidBefore,omitempty"`
}

UserLockState is the JSON value stored in LOCKED_USERS_BUCKET for a username.

api-server is the sole producer: it writes an entry whenever a user is locked or unlocked (see its setUserLocked), and its own AuthMiddleware reads the bucket directly on every request as a fast-path check.

ssh-proxy is a consumer: it subscribes to bucket changes (see NATSClient.SubscribeKVChanges, which delivers a KVEvent per write) and, on any event decoding to UserLockState.Locked == true, closes its live SSH connection(s) for that username. It should ignore Locked == false — unlocking a web account doesn't imply an SSH session should be allowed to resume; the user reconnects normally on their next attempt.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL