service

type APIKeyItem struct {
	KeyMetadata
	// ShortName is the Kubernetes Secret name (without namespace prefix).
	ShortName string
}

type APIKeyResult struct {
	RawToken string // shown once only
	KeyMetadata
}

type APIKeyService interface {
	Create(ctx context.Context, input CreateAPIKeyInput) (*APIKeyResult, *domain.AppError)
	List(ctx context.Context) ([]APIKeyItem, *domain.AppError)
	ListByTeamAndUser(ctx context.Context, team, user string) ([]APIKeyItem, *domain.AppError)
	Get(ctx context.Context, keyID string) (*APIKeyItem, *domain.AppError)
	Delete(ctx context.Context, keyID string) *domain.AppError
	// Promote elevates a locally-created key to a global key by syncing it
	// through the ws-proxy manager to all Worker clusters.
	Promote(ctx context.Context, keyID string) *domain.AppError
}

type ClusterConfigSink interface {
	ApplyClusterConfig(ctx context.Context, cfg cluster.ClusterConfig) error
}

type ClusterService interface {
	// List returns the cluster catalog sorted by ID. When store or localID are
	// empty the result is a single-entry list containing the local cluster, or an
	// empty slice when neither is configured. The list is a defensive copy; the
	// caller may mutate it freely.
	List(ctx context.Context) ([]gen.ClusterSummary, *domain.AppError)
}

type CreateAPIKeyInput struct {
	Namespace   string
	User        string
	Team        string
	Description string
	ExpiresAt   time.Time // zero means no expiry
	// Import mode fields (admin-only).
	// When TokenHash is non-empty the key is imported using the given hash
	// (via CreateFromHash) instead of generating a new random token.
	TokenHash  string
	HashPrefix string
	IssuedAt   time.Time // preserve original issue time (import mode)
}

type CreateKeyRequest struct {
	Namespace   string
	User        string
	Team        string
	Role        string
	Description string
	QuotaURL    string
	ExpiresAt   string // RFC3339; empty = never expires

	// Import/promote mode: when TokenHash + HashPrefix are set the Hub calls
	// CreateFromHash instead of generating a new token.
	TokenHash  string
	HashPrefix string
	IssuedAt   string // RFC3339
	RawToken   string // plaintext token for promote
}

type CreateKeyResponse struct {
	RawToken   string
	KeyID      string
	TokenHash  string
	HashPrefix string
	IssuedAt   string // RFC3339
}

type CreateSandboxEnvInput struct {
	Name      string
	Namespace string
	Team      string // copied from auth, injected as label
	User      string // copied from auth, injected as label

	TemplateRef agentsv1alpha1.SandboxEnvTemplateRef
	Mode        agentsv1alpha1.SandboxEnvMode
	Overrides   *agentsv1alpha1.EnvOverridesSpec
	// ImagePullSecret, when non-nil, instructs the service to materialise a
	// dockerconfigjson Secret named ips-{envName} with an OwnerRef pointing
	// at the Env (cascade-delete free). The Env Reconciler stamps a
	// LocalObjectReference to that Secret into every member Pool.
	ImagePullSecret *gen.ImagePullSecretInput

	Labels      map[string]string
	Annotations map[string]string
}

type CreateSandboxInput struct {
	ClusterID       string // target cluster ID parsed from pool name prefix; empty means local
	PoolName        string
	Namespace       string
	Image           string
	ContainerImages map[string]string
	Labels          map[string]string
	Annotations     map[string]string
	Metadata        map[string]string
	StartupTimeout  time.Duration // 0 means no timeout
	IdleTimeout     time.Duration // 0 means no expiry
	// RequestedScalingGroup, when non-empty, hard-scopes pool selection to the
	// env's member pools whose autoscaling group
	// (EnvClusterMemberConfig.ScalingGroup) equals this value. If no member of
	// the env belongs to that group the create fails (503) rather than falling
	// back to another group. Empty = no constraint. Set from the reserved
	// metadata key MetaKeyScalingGroup by the create handlers.
	RequestedScalingGroup string
	// PostStartHooks are actions to run after the sandbox transitions Starting → Running.
	// Serialized to a pod annotation at claim time; consumed by the controller.
	PostStartHooks []poststarthooks.Action

	// NetworkPolicy, when non-nil, overrides the Pool's Env-default egress policy
	// for this sandbox only (E2B create body: network / allow_internet_access).
	// Rejected when the target Pool has no networkPolicy (no filter sidecar).
	NetworkPolicy *agentsv1alpha1.SandboxNetworkPolicy
}

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

type EnvRouter interface {
	Resolve(ns, clusterID, poolOrEnvName string) envscheduler.ResolveResult
	// SelectPool picks a member pool of envKey. scalingGroup, when non-empty,
	// hard-scopes the choice to that autoscaling group (returns "" when the
	// group has no member). Empty = no constraint.
	SelectPool(envKey types.NamespacedName, scalingGroup string) string
	// SelectForeignTarget returns the cluster ID and member pool a create for
	// envKey should be forwarded to (local has no idle capacity for the group,
	// a foreign cluster's member does); ok is false when it should be served
	// locally.
	SelectForeignTarget(envKey types.NamespacedName, scalingGroup string) (clusterID, memberPool string, ok bool)
}

type EnvShellService interface {
	// List returns a lightweight summary of the SandboxEnvs in namespace
	// visible to the caller. When team/user are non-empty the result is
	// filtered by the standard scheduling.navix.sh/{team,user} labels
	// (matching the Pool model). Callers needing the full spec/status fetch
	// each Env via Get.
	List(ctx context.Context, namespace, team, user string) ([]gen.SandboxEnvSummary, *domain.AppError)
	// Get returns a single Env or NotFound.
	Get(ctx context.Context, namespace, name string) (*gen.SandboxEnv, *domain.AppError)
	// Create posts a new SandboxEnv shell. The body carries TemplateRef +
	// Overrides + optional ImagePullSecret only — Members are added via
	// AddMember (from the embedded MemberPoolService), which also
	// materialises the matching autoscaling group automatically.
	Create(ctx context.Context, input CreateSandboxEnvInput) (*gen.SandboxEnv, *domain.AppError)
	// Update patches Overrides / ImagePullSecret on an existing Env.
	// Members and autoscaling groups are intentionally not part of this
	// surface — use the dedicated CRUD methods from the embedded
	// sub-services to avoid accidental wholesale replacement.
	Update(ctx context.Context, input UpdateSandboxEnvInput) (*gen.SandboxEnv, *domain.AppError)
	// Delete issues a foreground delete on the Env. Member Pools are
	// cascade-deleted via OwnerReferences (controller=true,
	// blockOwnerDeletion=true) stamped by the Env Reconciler.
	Delete(ctx context.Context, namespace, name string) (*gen.DeleteSandboxEnvResult, *domain.AppError)
	// ListEvents returns recent K8s Events emitted against the Env and its
	// member SandboxPools, merged and sorted descending by lastTimestamp.
	// Drives the activity timeline on the Env detail page in the dashboard.
	ListEvents(ctx context.Context, namespace, name string, limit int) ([]gen.EnvEvent, *domain.AppError)
}

type ExecTokenInfo struct {
	SandboxID  string
	Namespace  string
	PodName    string
	Containers []string
}

type ExecTokenRecord struct {
	SandboxID  string
	Namespace  string
	PodName    string
	Containers []string
	ExpiresAt  time.Time
}

type ExtProcClient interface {
	PushRoute(ctx context.Context, r RouteInfo) error
	EvictRoute(ctx context.Context, sandboxID string) error
	GetLastActive(ctx context.Context) (map[string]time.Time, error)
	Close() error
}

type IAMResolveResult struct {
	// Username is the normalised username.
	Username string
	// Team is the team derived from ScitixQuota labels. Empty when no quota found.
	Team string
	// Namespace is the effective Kubernetes namespace to use for this user.
	// When the computed namespace (t-{team}-{username}) exists in the cluster it
	// equals that value; otherwise it falls back to "default".
	Namespace string
	// QuotaURL is the quota URL label value, if found.
	QuotaURL string
}

type IAMService interface {
	// ResolveNamespace resolves the effective namespace for a given team+user pair.
	// Results are cached permanently (until process restart) for performance.
	ResolveNamespace(ctx context.Context, team, user string) (string, *domain.AppError)
}

type KeyMetadata struct {
	// KeyID is the fully qualified secret identifier: "<namespace>/<name>".
	KeyID       string
	Namespace   string
	Role        string
	User        string
	Team        string
	Description string
	IssuedAt    time.Time
	ExpiresAt   time.Time // zero value means no expiry
	// SyncSource is "global" when the key was created/synced via ws-proxy.
	// Empty means locally-created or a legacy resource — both are treated as non-global.
	SyncSource string
	// RawToken is the full raw API key recovered from storage. Empty for legacy keys
	// that pre-date plaintext storage. Exposed via API to authorised callers for recovery.
	RawToken string
}

type LastCreateBumper interface {
	// Bump records the current time as the most-recent Sandbox.Create
	// for the named Pool. Must be safe to call from the request hot
	// path; the production implementation takes a brief mutex on an
	// in-memory map.
	Bump(namespace, name string)
}

type ListSandboxesResult struct {
	Items []gen.Sandbox
	Total int
}

type OrganizationService interface {
	// ListTeams returns all unique team names found across API Key secrets.
	ListTeams(ctx context.Context) ([]string, *domain.AppError)

	// ListUsersByTeam returns all unique user names belonging to the given team,
	// derived from API Key secrets filtered by team label.
	ListUsersByTeam(ctx context.Context, team string) ([]string, *domain.AppError)

	// ListNamespaces returns all Kubernetes namespace names visible to the operator.
	ListNamespaces(ctx context.Context) ([]string, *domain.AppError)
}

type QuotaService interface {
	// ListForUser returns all quotas matching the given user and team. When
	// the underlying provider is disabled the result is an empty list, not
	// an error — callers should treat that as "feature unavailable".
	ListForUser(ctx context.Context, user, team string) ([]gen.Quota, *domain.AppError)
}

type RegistryStore interface {
	LookupRegistry(host string) (clusterID, typ string, ok bool)
	RegistryForType(clusterID, typ string) (host string, ok bool)
}

type RouteInfo struct {
	SandboxID string
	Namespace string
	PodName   string
}

type SandboxEnvService interface {
	EnvShellService
	envmember.MemberPoolService
	envautoscaler.AutoscalerService
}

type SandboxListFilter struct {
	Namespace string
	PoolName  string
	Status    string // comma-separated multi-value supported (e.g. "Running,Failed")
	Team      string // when non-empty, only return sandboxes with this team label
	User      string // when non-empty, only return sandboxes with this user label
	Limit     int    // default 20, max 100; 0 means no limit
	Offset    int
}

type SandboxService interface {
	Create(ctx context.Context, input CreateSandboxInput) (*gen.Sandbox, *domain.AppError)
	List(ctx context.Context, filter SandboxListFilter) (*ListSandboxesResult, *domain.AppError)
	Get(ctx context.Context, namespace, sandboxID string) (*gen.Sandbox, *domain.AppError)
	Delete(ctx context.Context, namespace, sandboxID string) (*gen.DeleteSandboxResult, *domain.AppError)
	// SetTimeout updates the idle timeout annotation on the sandbox pod.
	// A timeout of 0 removes the annotation (no expiry).
	SetTimeout(ctx context.Context, namespace, sandboxID string, timeout time.Duration) *domain.AppError
	// GetLogs retrieves logs for a sandbox. For active sandboxes it fetches live
	// logs from the K8s API; for runtime sources it reads the log file via exec.
	GetLogs(ctx context.Context, namespace, sandboxID string, params gen.GetSandboxLogsParams) (*gen.SandboxLogsResult, *domain.AppError)
	// CreateExecToken generates a single-use exec token (TTL 30 s) for the given sandbox.
	// The sandbox must be in the Running phase.
	CreateExecToken(ctx context.Context, namespace, sandboxID string) (string, *domain.AppError)
	// ValidateExecToken validates and consumes the token.
	// Returns ExecTokenInfo on success, or a 401 AppError if the token is invalid / expired.
	ValidateExecToken(tokenStr string) (*ExecTokenInfo, *domain.AppError)
	// ExecCommand runs a one-shot command inside the sandbox pod (non-interactive, no TTY).
	// The sandbox must be in Running phase. clientset must be non-nil.
	ExecCommand(ctx context.Context, namespace, sandboxID string, req gen.ExecCommandRequest) (*gen.ExecCommandResult, *domain.AppError)
	// IsReady checks if all runtime readiness probes for a sandbox pass.
	// If a runtime has no ReadinessProbe configured, it is considered ready.
	IsReady(ctx context.Context, namespace, sandboxID string) (*gen.SandboxReadinessResult, *domain.AppError)
}

type SandboxTemplateService interface {
	// List returns templates visible to the caller (auth). isAdmin=true bypasses
	// visibility filtering and returns all templates.
	List(ctx context.Context, auth domain.AuthInfo, isAdmin bool) ([]gen.SandboxTemplate, *domain.AppError)
	// Get returns a single template if it is visible to the caller. isAdmin=true
	// bypasses visibility filtering. Returns ErrCodeNotFound when the template
	// does not exist or the caller cannot see it (to avoid leaking names).
	Get(ctx context.Context, name string, auth domain.AuthInfo, isAdmin bool) (*gen.SandboxTemplate, *domain.AppError)
	// Admin only:
	Create(ctx context.Context, tmpl *agentsv1alpha1.SandboxTemplate) (*gen.SandboxTemplate, *domain.AppError)
	Update(ctx context.Context, tmpl *agentsv1alpha1.SandboxTemplate) (*gen.SandboxTemplate, *domain.AppError)
	Delete(ctx context.Context, name string) *domain.AppError
	// CreateOrUpdate upserts a SandboxTemplate. It is used by SyncService to apply
	// sync events from ws-proxy. The operation is idempotent: if the template already
	// exists its spec is replaced; otherwise it is created.
	CreateOrUpdate(ctx context.Context, tmpl *agentsv1alpha1.SandboxTemplate) *domain.AppError
	// StripStaleGlobalLabels removes the sync-source=global label from any local
	// template whose name is NOT present in knownNames. This corrects templates
	// that were mistakenly (or historically) labeled as global but no longer exist
	// on the master cluster, preventing delete requests from being forwarded to
	// ws-proxy and receiving a 404.
	StripStaleGlobalLabels(ctx context.Context, knownNames map[string]struct{}) *domain.AppError
}

type SyncHTTPError struct {
	Status  int
	Message string
}

type SyncService interface {
	// OnConnect registers a new ClientConn (produced by wsmux.DialGRPC after
	// a fresh /v1/ws/sync upgrade). Returns a connection generation ID that
	// must be passed back to OnDisconnect so that a stale teardown does not
	// race against a newer connect.
	OnConnect(conn *grpc.ClientConn) uint64

	// OnDisconnect tears down all background Watch goroutines associated
	// with connID and clears the ClientConn — but only if connID still
	// matches the currently-registered conn.
	OnDisconnect(connID uint64)

	RequestCreate(ctx context.Context, req CreateKeyRequest) (*CreateKeyResponse, error)
	RequestDelete(ctx context.Context, name string) error
	RequestTemplateCreate(ctx context.Context, raw json.RawMessage) error
	RequestTemplateUpdate(ctx context.Context, raw json.RawMessage) error
	RequestTemplateDelete(ctx context.Context, name string) error
}

type URLKind = cluster.URLKind

type UpdateSandboxEnvInput struct {
	Name      string
	Namespace string

	Overrides *agentsv1alpha1.EnvOverridesSpec
	// ImagePullSecret, when non-nil, upserts the dockerconfigjson Secret
	// backing this Env's image-pull credentials. Nil means leave existing
	// Secret untouched.
	ImagePullSecret *gen.ImagePullSecretInput
}