Documentation
¶
Index ¶
- type AppError
- func NewBadRequest(msg string) *AppError
- func NewConflict(msg string) *AppError
- func NewForbidden(msg string) *AppError
- func NewGatewayTimeout(msg string, cause error) *AppError
- func NewInternal(msg string, cause error) *AppError
- func NewNotFound(msg string) *AppError
- func NewServiceUnavailable(msg string) *AppError
- func NewTooManyRequests(msg string, cause error, detail any) *AppError
- func NewUnauthorized(msg string) *AppError
- type AuthInfo
- type AvailablePoolSummary
- type AvailablePoolsDetail
- type AvailableQuotaURLSummary
- type AvailableQuotaURLsDetail
- type AvailableTemplateSummary
- type AvailableTemplatesDetail
- type BusinessErrorCode
- type ErrorCode
- type PoolStatusDetail
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 ¶
NewBadRequest constructs a 400 AppError.
func NewGatewayTimeout ¶ added in v0.0.10
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 ¶
NewInternal constructs a 500 AppError with an underlying cause.
func NewServiceUnavailable ¶
NewServiceUnavailable constructs a 503 AppError.
func NewTooManyRequests ¶
NewTooManyRequests constructs a 429 AppError with an underlying cause.
func NewUnauthorized ¶
NewUnauthorized constructs a 401 AppError.
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 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.