admin

Documentation

Overview

Package admin provides system-level and tenant-level management for the ctrlplane. It includes tenant CRUD, quota management, system statistics, provider status, and audit logging.

Index

• type AuditEntry
• type AuditQuery
• type AuditResult
• type CreateTenantRequest
• type ListTenantsOptions
• type ProviderStatus
• type Quota
• type QuotaSnapshot
• type QuotaUsage
• type Service
  • func NewService(store Store, instStore instance.Store, netStore network.Store, ...) Service
• type Store
• type SystemStats
• type Tenant
• type TenantListResult
• type TenantStatus
• type UpdateTenantRequest

Types

type AuditEntry

type AuditEntry struct {
	ctrlplane.Entity

	TenantID   string         `db:"tenant_id"   json:"tenant_id"`
	ActorID    string         `db:"actor_id"    json:"actor_id"`
	ActorType  string         `db:"actor_type"  json:"actor_type"`
	Resource   string         `db:"resource"    json:"resource"`
	ResourceID string         `db:"resource_id" json:"resource_id"`
	Action     string         `db:"action"      json:"action"`
	Details    map[string]any `db:"details"     json:"details,omitempty"`
	IPAddress  string         `db:"ip_address"  json:"ip_address,omitempty"`
}

AuditEntry records a single auditable action in the system.

type AuditQuery

type AuditQuery struct {
	TenantID string    `json:"tenant_id,omitempty"`
	ActorID  string    `json:"actor_id,omitempty"`
	Resource string    `json:"resource,omitempty"`
	Action   string    `json:"action,omitempty"`
	Since    time.Time `json:"since"`
	Until    time.Time `json:"until"`
	Limit    int       `json:"limit"`
}

AuditQuery configures an audit log query.

type AuditResult

type AuditResult struct {
	Items      []AuditEntry `json:"items"`
	NextCursor string       `json:"next_cursor,omitempty"`
	Total      int          `json:"total"`
}

AuditResult holds a page of audit entries.

type CreateTenantRequest

type CreateTenantRequest struct {
	Name       string            `json:"name"                  validate:"required"`
	Plan       string            `default:"free"               json:"plan"`
	ExternalID string            `json:"external_id,omitempty"`
	Quota      *Quota            `json:"quota,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

CreateTenantRequest holds the parameters for creating a tenant.

type ListTenantsOptions

type ListTenantsOptions struct {
	Status string `json:"status,omitempty"`
	Cursor string `json:"cursor,omitempty"`
	Limit  int    `json:"limit,omitempty"`
}

ListTenantsOptions configures tenant listing.

type ProviderStatus

type ProviderStatus struct {
	Name         string   `json:"name"`
	Region       string   `json:"region"`
	Healthy      bool     `json:"healthy"`
	Instances    int      `json:"instances"`
	Capabilities []string `json:"capabilities"`
}

ProviderStatus describes the operational status of a provider.

type Quota

type Quota struct {
	MaxInstances int `db:"max_instances"  json:"max_instances"`
	MaxCPUMillis int `db:"max_cpu_millis" json:"max_cpu_millis"`
	MaxMemoryMB  int `db:"max_memory_mb"  json:"max_memory_mb"`
	MaxDiskMB    int `db:"max_disk_mb"    json:"max_disk_mb"`
	MaxDomains   int `db:"max_domains"    json:"max_domains"`
	MaxSecrets   int `db:"max_secrets"    json:"max_secrets"`
}

Quota defines resource limits per tenant.

type QuotaSnapshot

type QuotaSnapshot struct {
	Instances int `json:"instances"`
	CPUMillis int `json:"cpu_millis"`
	MemoryMB  int `json:"memory_mb"`
	DiskMB    int `json:"disk_mb"`
	Domains   int `json:"domains"`
	Secrets   int `json:"secrets"`
}

QuotaSnapshot captures a point-in-time usage count.

type QuotaUsage

type QuotaUsage struct {
	Tenant *Tenant       `json:"tenant"`
	Quota  Quota         `json:"quota"`
	Used   QuotaSnapshot `json:"used"`
}

QuotaUsage shows current usage against quota limits.

type Service

type Service interface {
	// CreateTenant creates a new tenant.
	CreateTenant(ctx context.Context, req CreateTenantRequest) (*Tenant, error)

	// GetTenant returns a tenant by ID.
	GetTenant(ctx context.Context, tenantID string) (*Tenant, error)

	// ListTenants returns tenants with optional filtering.
	ListTenants(ctx context.Context, opts ListTenantsOptions) (*TenantListResult, error)

	// UpdateTenant modifies a tenant.
	UpdateTenant(ctx context.Context, tenantID string, req UpdateTenantRequest) (*Tenant, error)

	// SuspendTenant suspends a tenant with a reason.
	SuspendTenant(ctx context.Context, tenantID string, reason string) error

	// UnsuspendTenant restores a suspended tenant.
	UnsuspendTenant(ctx context.Context, tenantID string) error

	// DeleteTenant removes a tenant.
	DeleteTenant(ctx context.Context, tenantID string) error

	// GetQuota returns quota usage for a tenant.
	GetQuota(ctx context.Context, tenantID string) (*QuotaUsage, error)

	// SetQuota updates quota limits for a tenant.
	SetQuota(ctx context.Context, tenantID string, quota Quota) error

	// SystemStats returns system-wide statistics.
	SystemStats(ctx context.Context) (*SystemStats, error)

	// ListProviders returns status of all registered providers.
	ListProviders(ctx context.Context) ([]ProviderStatus, error)

	// QueryAuditLog queries the audit log.
	QueryAuditLog(ctx context.Context, opts AuditQuery) (*AuditResult, error)
}

Service is the admin management interface for system and tenant operations.

func NewService

func NewService(
	store Store,
	instStore instance.Store,
	netStore network.Store,
	secStore secrets.Store,
	providers *provider.Registry,
	events event.Bus,
	auth auth.Provider,
) Service

NewService creates a new admin service.

type Store

type Store interface {
	// InsertTenant persists a new tenant.
	InsertTenant(ctx context.Context, tenant *Tenant) error

	// GetTenant retrieves a tenant by ID.
	GetTenant(ctx context.Context, tenantID string) (*Tenant, error)

	// GetTenantBySlug retrieves a tenant by slug.
	GetTenantBySlug(ctx context.Context, slug string) (*Tenant, error)

	// ListTenants returns tenants with optional filtering.
	ListTenants(ctx context.Context, opts ListTenantsOptions) (*TenantListResult, error)

	// UpdateTenant persists changes to a tenant.
	UpdateTenant(ctx context.Context, tenant *Tenant) error

	// DeleteTenant removes a tenant.
	DeleteTenant(ctx context.Context, tenantID string) error

	// CountTenants returns the total number of tenants.
	CountTenants(ctx context.Context) (int, error)

	// CountTenantsByStatus returns the number of tenants in a given status.
	CountTenantsByStatus(ctx context.Context, status TenantStatus) (int, error)

	// InsertAuditEntry persists an audit log entry.
	InsertAuditEntry(ctx context.Context, entry *AuditEntry) error

	// QueryAuditLog returns audit entries matching the query.
	QueryAuditLog(ctx context.Context, opts AuditQuery) (*AuditResult, error)
}

Store is the persistence interface for admin entities.

type SystemStats

type SystemStats struct {
	TotalTenants     int `json:"total_tenants"`
	ActiveTenants    int `json:"active_tenants"`
	TotalInstances   int `json:"total_instances"`
	RunningInstances int `json:"running_instances"`
	TotalProviders   int `json:"total_providers"`
	HealthyProviders int `json:"healthy_providers"`
}

SystemStats holds system-wide statistics.

type Tenant

type Tenant struct {
	ctrlplane.Entity

	ExternalID  string            `db:"external_id"  json:"external_id,omitempty"`
	Name        string            `db:"name"         json:"name"`
	Slug        string            `db:"slug"         json:"slug"`
	Status      TenantStatus      `db:"status"       json:"status"`
	Plan        string            `db:"plan"         json:"plan"`
	Quota       Quota             `db:"quota"        json:"quota"`
	SuspendedAt *time.Time        `db:"suspended_at" json:"suspended_at,omitempty"`
	Metadata    map[string]string `db:"metadata"     json:"metadata,omitempty"`
}

Tenant represents a tenant or organization in the control plane.

type TenantListResult

type TenantListResult struct {
	Items      []*Tenant `json:"items"`
	NextCursor string    `json:"next_cursor,omitempty"`
	Total      int       `json:"total"`
}

TenantListResult holds a page of tenants.

type TenantStatus

type TenantStatus string

TenantStatus represents the lifecycle state of a tenant.

const (
	// TenantActive indicates the tenant is active.
	TenantActive TenantStatus = "active"

	// TenantSuspended indicates the tenant is suspended.
	TenantSuspended TenantStatus = "suspended"

	// TenantDeleted indicates the tenant is deleted.
	TenantDeleted TenantStatus = "deleted"
)

type UpdateTenantRequest

type UpdateTenantRequest struct {
	Name     *string           `json:"name,omitempty"`
	Plan     *string           `json:"plan,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

UpdateTenantRequest holds the parameters for updating a tenant.