nats

package
v0.43.0 Latest Latest
Warning

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

Go to latest
Published: Aug 19, 2026 License: AGPL-3.0 Imports: 12 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"
)

Variables

This section is empty.

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

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  int              `yaml:"replicas" json:"replicas"`
}

BucketOptions holds options for the JetStream cache bucket.

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 CAS-updating it to empty owner/no expiration. It only releases if we still own the lock; otherwise it is a no-op.

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)

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
}

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) 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).

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"`
	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 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.NewKVSubscriber, 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