environments

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package environments manages sandboxed dev environment lifecycle.

Index

Constants

This section is empty.

Variables

View Source 
var ErrPoolEmpty = errors.New("warm pool: no container available")

ErrPoolEmpty is returned when no warm container is available for the requested template.

Functions

This section is empty.

Types

type CreatePreviewRequest 

type CreatePreviewRequest struct {
	Name string `json:"name"`
	Port int    `json:"port"`
}

CreatePreviewRequest holds parameters for creating a preview route.

type CreateRequest 

type CreateRequest struct {
	Name                 string `json:"name"`
	TemplateID           string `json:"template_id,omitempty"`
	LeaseDurationSeconds *int   `json:"lease_duration_seconds,omitempty"`
}

CreateRequest holds parameters for creating an environment.

type Environment 

type Environment struct {
	ID                   string `json:"id"`
	TenantID             string `json:"tenant_id"`
	Name                 string `json:"name"`
	TemplateID           string `json:"template_id"`
	Status               string `json:"status"`
	ContainerID          string `json:"container_id,omitempty"`
	VolumeName           string `json:"-"`
	LeaseExpiresAt       *int64 `json:"lease_expires_at,omitempty"`
	LeaseDurationSeconds int    `json:"lease_duration_seconds"`
	LastActivityAt       *int64 `json:"last_activity_at,omitempty"`
	CreatedAt            int64  `json:"created_at"`
	UpdatedAt            int64  `json:"updated_at"`
}

Environment represents a sandboxed dev environment.

type ExecRequest 

type ExecRequest struct {
	Command []string `json:"command"`
	WorkDir string   `json:"work_dir,omitempty"`
	Timeout int      `json:"timeout,omitempty"` // seconds, max 300, default 60
}

ExecRequest holds parameters for executing a command in an environment.

type ExecResponse 

type ExecResponse struct {
	ExitCode   int    `json:"exit_code"`
	Stdout     string `json:"stdout"`
	Stderr     string `json:"stderr"`
	Truncated  bool   `json:"truncated"`
	TimedOut   bool   `json:"timed_out"`
	DurationMs int64  `json:"duration_ms"`
}

ExecResponse holds the result of a command execution.

type Manager 

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

Manager manages environment lifecycle.

func NewManager 

func NewManager(db *sql.DB, docker docker.Client, baseDomain, traefikConfigDir string) *Manager

NewManager creates an environment manager.

func (*Manager) Create 

func (m *Manager) Create(ctx context.Context, tenantID string, req CreateRequest) (*Environment, error)

Create provisions a new environment.

func (*Manager) CreatePreview 

func (m *Manager) CreatePreview(ctx context.Context, tenantID, envID string, req CreatePreviewRequest) (*Preview, error)

CreatePreview creates a preview route for an environment port.

func (*Manager) Delete 

func (m *Manager) Delete(ctx context.Context, tenantID, envID string) error

Delete destroys an environment: stops container, removes volume, deletes record.

func (*Manager) DeletePreview 

func (m *Manager) DeletePreview(ctx context.Context, tenantID, envID, previewID string) error

DeletePreview removes a preview route.

func (*Manager) Exec 

func (m *Manager) Exec(ctx context.Context, tenantID, envID string, req ExecRequest) (*ExecResponse, error)

Exec executes a command in a running environment.

func (*Manager) ExtendLease 

func (m *Manager) ExtendLease(ctx context.Context, tenantID, envID string, durationSec int) error

ExtendLease extends the lease of a running environment.

func (*Manager) Get 

func (m *Manager) Get(ctx context.Context, tenantID, envID string) (*Environment, error)

Get returns an environment by ID, scoped to tenant.

func (*Manager) GetTemplate 

func (m *Manager) GetTemplate(ctx context.Context, templateID string) (*Template, error)

GetTemplate returns a template by ID.

func (*Manager) List 

func (m *Manager) List(ctx context.Context, tenantID string, limit, offset int) ([]*Environment, error)

List returns environments for a tenant with pagination.

func (*Manager) ListPreviews 

func (m *Manager) ListPreviews(ctx context.Context, tenantID, envID string) ([]*Preview, error)

ListPreviews returns all preview routes for an environment.

func (*Manager) ListTemplates 

func (m *Manager) ListTemplates(ctx context.Context) ([]*Template, error)

ListTemplates returns all available templates.

func (*Manager) ReconcileStale 

func (m *Manager) ReconcileStale(ctx context.Context) error

ReconcileStale cleans up stuck or expired environments.

func (*Manager) SetExternalTLSTerminated 

func (m *Manager) SetExternalTLSTerminated(enabled bool)

SetExternalTLSTerminated configures preview routes for deployments where a trusted upstream proxy terminates public TLS before traffic reaches Traefik. Enabling it assumes public requests reach these routes only through that configured proxy; the route middleware then sets X-Forwarded-Proto to https.

func (*Manager) SetPool 

func (m *Manager) SetPool(p *PoolManager)

SetPool sets the warm pool manager for faster environment creation.

func (*Manager) Start 

func (m *Manager) Start(ctx context.Context, tenantID, envID string) error

Start starts a stopped environment.

func (*Manager) Stop 

func (m *Manager) Stop(ctx context.Context, tenantID, envID string) error

Stop stops a running environment.

func (*Manager) StopAllForTenant 

func (m *Manager) StopAllForTenant(_ context.Context, tenantID string)

StopAllForTenant stops active environment containers (including claimed warm-pool containers, found by DB row rather than label) and removes their Traefik files while keeping workspace and preview records for reactivation. A container that fails to stop keeps its row so the next suspend retries.

func (*Manager) SyncWorkspace 

func (m *Manager) SyncWorkspace(ctx context.Context, tenantID, envID string, req SyncRequest) error

SyncWorkspace syncs code into an environment's /workspace directory via git.

type PoolConfig 

type PoolConfig struct {
	Enabled      bool          // whether the pool is active
	PoolSize     int           // target containers per template (default: 2)
	MaxTotal     int           // max warm containers across all templates (default: 6)
	RefillPeriod time.Duration // how often to check pool (default: 60s)
}

PoolConfig configures the warm container pool.

type PoolManager 

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

PoolManager manages a pool of pre-warmed containers for fast environment creation.

func NewPoolManager 

func NewPoolManager(db *sql.DB, docker docker.Client, cfg PoolConfig) *PoolManager

NewPoolManager creates a new pool manager.

func (*PoolManager) Acquire 

func (p *PoolManager) Acquire(ctx context.Context, templateID string) (containerID, volumeName string, err error)

Acquire claims a warm container for the given template. Returns container ID and volume name. The caller is responsible for renaming/reconnecting the container. Returns ErrPoolEmpty if no container is available.

func (*PoolManager) AcquireForEnvironment 

func (p *PoolManager) AcquireForEnvironment(ctx context.Context, templateID, tenantID, envID string) (containerID, volumeName string, err error)

AcquireForEnvironment assigns ownership to the creating environment in the same transaction that marks the pool row claimed. GC can therefore never see a claimed container or volume without an owning database record.

func (*PoolManager) Drain 

func (p *PoolManager) Drain(ctx context.Context) error

Drain stops and removes all warm pool containers and cleans up the DB.

func (*PoolManager) Run 

func (p *PoolManager) Run(ctx context.Context)

Run starts the background refill loop. Blocks until ctx is cancelled.

func (*PoolManager) Stats 

func (p *PoolManager) Stats(ctx context.Context) (map[string]int, error)

Stats returns the number of ready containers per template.

type Preview 

type Preview struct {
	ID            string `json:"id"`
	EnvironmentID string `json:"environment_id"`
	TenantID      string `json:"tenant_id"`
	Name          string `json:"name"`
	Port          int    `json:"port"`
	DNSLabel      string `json:"dns_label"`
	URL           string `json:"url,omitempty"`
	CreatedAt     int64  `json:"created_at"`
	UpdatedAt     int64  `json:"updated_at"`
}

Preview represents a preview route exposing an environment port via Traefik.

type SyncRequest 

type SyncRequest struct {
	GitURL string `json:"git_url,omitempty"`
	GitRef string `json:"git_ref,omitempty"` // branch/tag/commit, default "HEAD"
}

SyncRequest holds parameters for syncing code into an environment.

type Template 

type Template struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	BaseImage    string `json:"base_image"`
	Description  string `json:"description"`
	MemoryMB     int    `json:"memory_mb"`
	CPUMillis    int    `json:"cpu_millicores"`
	DiskMB       int    `json:"disk_mb"`
	EgressPolicy string `json:"egress_policy"`
	CreatedAt    int64  `json:"created_at"`
	UpdatedAt    int64  `json:"updated_at"`
}

Template describes a pre-configured environment type.

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.