domain

package
v0.0.13 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppError

type AppError struct {
	Code    ErrorCode
	BizCode BusinessErrorCode // optional; when non-empty, serialised into the errorCode response field
	Message string
	Cause   error // not exposed to callers; used for logging
	Detail  any   // structured extra info (e.g. PoolStatusDetail), serialized in response
}

AppError is a domain-level error that carries an HTTP-status-mapped code, a user-visible message, an optional wrapped cause for logging, and optional structured detail for the API response.

func NewBadRequest

func NewBadRequest(msg string) *AppError

NewBadRequest constructs a 400 AppError.

func NewConflict

func NewConflict(msg string) *AppError

NewConflict constructs a 409 AppError.

func NewForbidden

func NewForbidden(msg string) *AppError

NewForbidden constructs a 403 AppError.

func NewGatewayTimeout added in v0.0.10

func NewGatewayTimeout(msg string, cause error) *AppError

NewGatewayTimeout reports that a bounded wait on something downstream (a sandbox runtime coming up, a post-start step finishing) ran out of time. Distinct from Internal so a caller can tell "it did not finish in time" — which is worth retrying — from "it failed".

func NewInternal

func NewInternal(msg string, cause error) *AppError

NewInternal constructs a 500 AppError with an underlying cause.

func NewNotFound

func NewNotFound(msg string) *AppError

NewNotFound constructs a 404 AppError.

func NewServiceUnavailable

func NewServiceUnavailable(msg string) *AppError

NewServiceUnavailable constructs a 503 AppError.

func NewTooManyRequests

func NewTooManyRequests(msg string, cause error, detail any) *AppError

NewTooManyRequests constructs a 429 AppError with an underlying cause.

func NewUnauthorized

func NewUnauthorized(msg string) *AppError

NewUnauthorized constructs a 401 AppError.

func (*AppError) Error

func (e *AppError) Error() string

func (*AppError) Unwrap

func (e *AppError) Unwrap() error

type AuthInfo

type AuthInfo struct {
	Namespace string
	Role      string
	User      string
	Team      string
	// AuthMethod indicates how the caller was authenticated: "apikey" or "jwt".
	AuthMethod string
	// Email is the user's email address (populated from JWT claims).
	Email string
	// Name is the user's display name (populated from JWT claims).
	Name string
	// KeyID names the API key this request came in on, empty for JWT callers.
	//
	// Present because a permission can belong to a CREDENTIAL rather than to
	// the person holding it: "this agent's key may create environments" has to
	// stop meaning anything the moment that key is deleted, which requires
	// knowing which key asked.
	KeyID string
	// Unattended marks a credential that acts with nobody watching, and is
	// therefore subject to the approval gate. It is a property of the key, not
	// of the caller's identity: the same person is exempt in the console — where
	// their click IS the approval — and gated through an agent.
	Unattended bool
	// ApprovedOps are the operations this credential is already allowed to
	// perform without asking, as recorded on the credential itself.
	//
	// Carried on AuthInfo because it arrives with the rest of the credential's
	// metadata and shares its cache — the alternative, reading it per gated
	// request, would put a Secret lookup in front of every write.
	ApprovedOps []string
}

AuthInfo holds the authenticated caller's identity extracted from the API key or JWT. It has no dependency on gin or net/http.

type AvailablePoolSummary

type AvailablePoolSummary struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace,omitempty"`
	Idle      int32  `json:"idle"`
	Running   int32  `json:"running"`
	Starting  int32  `json:"starting"`
}

AvailablePoolSummary is a lightweight pool descriptor included in the discovery detail when a client references a missing pool. It intentionally avoids leaking full pool spec to keep the error response compact.

type AvailablePoolsDetail

type AvailablePoolsDetail struct {
	AvailablePools []AvailablePoolSummary `json:"availablePools"`
	Hint           string                 `json:"hint,omitempty"`
}

AvailablePoolsDetail is attached to 404 Not Found when CreateSandbox references a pool that does not exist. The caller can pick a pool from AvailablePools and retry without a round-trip to ListSandboxPools.

type AvailableQuotaURLSummary

type AvailableQuotaURLSummary struct {
	URL   string `json:"url"`
	Queue string `json:"queue,omitempty"`
	Free  string `json:"free,omitempty"`
}

AvailableQuotaURLSummary describes one quota that the caller may reference via spec.reservation.quotaURL.

type AvailableQuotaURLsDetail

type AvailableQuotaURLsDetail struct {
	AvailableQuotaURLs []AvailableQuotaURLSummary `json:"availableQuotaURLs"`
	Hint               string                     `json:"hint,omitempty"`
}

AvailableQuotaURLsDetail is attached to 400 Bad Request when a pool requests reservation but does not specify a quotaURL.

type AvailableTemplateSummary

type AvailableTemplateSummary struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	SyncSource  string `json:"syncSource,omitempty"`
}

AvailableTemplateSummary is a lightweight template descriptor included in the discovery detail when a client references a missing template.

type AvailableTemplatesDetail

type AvailableTemplatesDetail struct {
	AvailableTemplates []AvailableTemplateSummary `json:"availableTemplates"`
	Hint               string                     `json:"hint,omitempty"`
}

AvailableTemplatesDetail is attached to 404 Not Found when CreateSandboxPool references a template that does not exist.

type BusinessErrorCode

type BusinessErrorCode string

BusinessErrorCode is a machine-readable business error code carried alongside specific AppErrors that require special frontend handling (e.g. redirecting the user to another page instead of showing a generic toast). It is intentionally orthogonal to the HTTP status code: the same HTTP status can carry different BusinessErrorCodes depending on the scenario.

type ErrorCode

type ErrorCode int

ErrorCode maps to HTTP status codes.

const (
	ErrCodeBadRequest          ErrorCode = 400
	ErrCodeUnauthorized        ErrorCode = 401
	ErrCodeForbidden           ErrorCode = 403
	ErrCodeNotFound            ErrorCode = 404
	ErrCodeConflict            ErrorCode = 409
	ErrCodeUnprocessableEntity ErrorCode = 422
	ErrCodeTooManyRequests     ErrorCode = 429
	ErrCodeServiceUnavailable  ErrorCode = 503
	ErrCodeInternal            ErrorCode = 500
	ErrCodeGatewayTimeout      ErrorCode = 504
)

type PoolStatusDetail

type PoolStatusDetail struct {
	Idle       int32  `json:"idle"`
	Running    int32  `json:"running"`
	Starting   int32  `json:"starting"`
	Stopping   int32  `json:"stopping"`
	Failed     int32  `json:"failed"`
	Hint       string `json:"hint,omitempty"`
	RetryAfter int    `json:"retryAfter,omitempty"` // seconds
}

PoolStatusDetail is attached to 409 Conflict when creating sandboxes and the pool has no idle pods available.

Jump to

Keyboard shortcuts

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