allocation

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 29, 2026 License: Apache-2.0, MIT Imports: 12 Imported by: 0

Documentation

Overview

Package allocation is the domain model for placing a session on a remote sandbox: which mode it uses, whether its owner may share a machine, and the identity of a shared machine. It performs no I/O.

Index

Constants

View Source 
const (
	// DefaultEmptyRetentionDays is how long a user machine with no live
	// session is kept when the config leaves the value unset.
	DefaultEmptyRetentionDays = 7
	// MaxEmptyRetentionDays bounds the setting; there is no "keep forever".
	MaxEmptyRetentionDays = 90
)
View Source 
const MaxOwnerIDLength = 512

MaxOwnerIDLength matches sessions.user_id.

View Source 
const UserModeEnvVar = "WEKNORA_SANDBOX_USER_ALLOCATION"

UserModeEnvVar opts a deployment into user-mode allocation. It must be set on every replica before any config is switched to "user".

Variables

This section is empty.

Functions

func EffectiveRetentionDays 

func EffectiveRetentionDays(stored int) int

EffectiveRetentionDays maps the stored value (0 = unset) onto days.

func EligibleForUser 

func EligibleForUser(kind OwnerKind, source AuthSource) bool

EligibleForUser is the whitelist itself: a server-verified web account, or an API external user whose subject came from the direct header or a signed token. Decide applies it at first use; the manager re-applies it to stored assignments so a row whose identity is no longer acceptable stops running.

func SetUserModeAvailable 

func SetUserModeAvailable(available bool)

SetUserModeAvailable is called once by the container after it knows whether the deployment can coordinate shared machines (env opt-in and Redis).

func UserModeAvailable 

func UserModeAvailable() bool

UserModeAvailable reports the deployment gate.

func UserModeRequestedByEnv 

func UserModeRequestedByEnv() bool

UserModeRequestedByEnv reports whether the operator asked for user mode.

func ValidateOwnerID 

func ValidateOwnerID(id string) error

ValidateOwnerID rejects ids that cannot be part of a machine identity.

func ValidateRetentionDays 

func ValidateRetentionDays(stored int) error

ValidateRetentionDays accepts 0 (use the default) through 90.

Types

type Assignment 

type Assignment struct {
	SessionID      string
	ConfigTenantID uint64
	ConfigID       string
	// Machine is the shared machine of a user-mode session; zero for a
	// session with a machine of its own.
	Machine    UserMachine
	ReleasedAt *time.Time
}

Assignment is the persisted placement of one session. Only the config address, the shared machine (if any) and the release time are stored; the mode and the workspace layout follow from whether there is a machine, and the session keeps both for life whatever the config switch says later.

func (Assignment) IsUser 

func (a Assignment) IsUser() bool

IsUser reports a session on a shared machine.

func (Assignment) Layout 

func (a Assignment) Layout() (workspace.Layout, error)

Layout is the workspace the session was assigned, independent of the config's current switch.

func (Assignment) Mode 

func (a Assignment) Mode() Mode

Mode is ModeUser for a session on a shared machine, ModeSession otherwise.

func (Assignment) Released 

func (a Assignment) Released() bool

Released reports a session whose workspace has been given back.

func (Assignment) UserMachine 

func (a Assignment) UserMachine() (UserMachine, bool)

UserMachine returns the shared machine a user-mode session lives on.

type AuthSource 

type AuthSource string

AuthSource is how the server authenticated the owner when the session was created or its owner was first bound. It is recorded server-side only. 

const (
	SourceUnknown         AuthSource = "unknown"
	SourceWeb             AuthSource = "web"
	SourceAPIDirectHeader AuthSource = "api_direct_header"
	SourceAPISignedToken  AuthSource = "api_signed_token"
	SourceAPITenantKey    AuthSource = "api_tenant_key"
	SourceAPIPlatformKey  AuthSource = "api_platform_key"
	SourceMCPEndpoint     AuthSource = "mcp_endpoint"
	SourceEmbed           AuthSource = "embed"
	SourceIM              AuthSource = "im"
	SourceInternal        AuthSource = "internal"
)

Sources stamped by the server. SourceUnknown is an empty or legacy row.

type DecideInput 

type DecideInput struct {
	ConfigMode        Mode
	Purpose           Purpose
	Owner             Owner
	SessionID         string
	UserModeAvailable bool
}

DecideInput is everything Decide needs; callers load it, Decide is pure.

type Decision 

type Decision struct {
	Mode   Mode
	Reason FallbackReason
}

Decision is the mode a session gets and why it differs from the config.

func Decide 

func Decide(in DecideInput) Decision

Decide applies the user-mode admission whitelist. Only a server-verified web account or API external user may share a machine; every other owner keeps a machine per session. Checks run in a fixed order so the recorded reason is deterministic: maintenance, deployment gate, invalid owner, shared entry or channel, unverified identity, session id shape.

type FallbackReason 

type FallbackReason string

FallbackReason explains why a session did not get the config's mode. The values are stable, non-sensitive tokens safe to show an admin. 

const (
	ReasonNone                    FallbackReason = ""
	ReasonMaintenanceDedicated    FallbackReason = "MAINTENANCE_DEDICATED"
	ReasonUserModeUnavailable     FallbackReason = "USER_MODE_UNAVAILABLE"
	ReasonOwnerIdentityInvalid    FallbackReason = "OWNER_IDENTITY_INVALID"
	ReasonSharedAPIKey            FallbackReason = "SHARED_API_KEY"
	ReasonSharedMCPEndpoint       FallbackReason = "SHARED_MCP_ENDPOINT"
	ReasonChannelIdentity         FallbackReason = "CHANNEL_IDENTITY_NOT_SUPPORTED"
	ReasonOwnerIdentityUnverified FallbackReason = "OWNER_IDENTITY_UNVERIFIED"
	ReasonSessionIDNotUUID        FallbackReason = "SESSION_ID_NOT_UUID"
	ReasonLegacySessionSandbox    FallbackReason = "LEGACY_SESSION_SANDBOX"
)

Reasons a placement stayed on a per-session machine.

type Mode 

type Mode string

Mode is how a session is placed on remote machines. 

const (
	// ModeSession gives the session a machine of its own (historical behaviour).
	ModeSession Mode = "session"
	// ModeUser places the session in a directory on its owner's shared machine.
	ModeUser Mode = "user"
)

func ParseMode 

func ParseMode(raw string) (Mode, error)

ParseMode accepts the stored config value. Empty means session.

type Owner 

type Owner struct {
	TenantID uint64
	ID       string
	Kind     OwnerKind
	Source   AuthSource
}

Owner is the persisted owner of a session as the allocator sees it.

type OwnerKind 

type OwnerKind string

OwnerKind classifies who sessions.user_id names. 

const (
	KindUnknown         OwnerKind = ""
	KindWebUser         OwnerKind = "web_user"
	KindAPIExternalUser OwnerKind = "api_external_user"
	KindAPITenantKey    OwnerKind = "api_tenant_key"
	KindAPIPlatformKey  OwnerKind = "api_platform_key"
	KindMCPEndpoint     OwnerKind = "mcp_endpoint"
	KindEmbed           OwnerKind = "embed"
	KindIM              OwnerKind = "im"
)

Kinds derived from owner_auth_source and the shape of user_id.

type Purpose 

type Purpose string

Purpose is why a session uses a sandbox. 

const (
	PurposeChat        Purpose = "chat"
	PurposeMaintenance Purpose = "maintenance"
)

Placement purposes. PurposeChat is an ordinary session. PurposeMaintenance is a skill-install session and stays on its own machine.

type UserMachine 

type UserMachine struct {
	OwnerTenantID  uint64
	OwnerID        string
	ConfigTenantID uint64
	ConfigID       string
}

UserMachine is the logical identity of one shared machine: one owner, one sandbox config. It is comparable so it can key maps. ConfigID must already be normalized (sandbox.NormalizeConfigID) and ConfigTenantID resolved.

func (UserMachine) Digest 

func (m UserMachine) Digest(namespace string) string

Digest is the hex SHA-256 of a length-prefixed canonical encoding, so no two identities share a digest by field-boundary ambiguity. The namespace is part of it: two deployments sharing one Redis never address each other's machines. It is the Redis hash tag, the DB key and the provider metadata.

func (UserMachine) Validate 

func (m UserMachine) Validate() error

Validate rejects identities that cannot address a machine.

Source Files

View all Source files

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.