system

package
v0.4.13-beta.13 Latest Latest
Warning

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

 Go to latest Published: Dec 28, 2025 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package system defines the public contract for daemon-level operations in dployr.

It models system health, registration, installation/upgrade, domain requests, mode management, and instance lifecycle sync with base over WebSockets. The concrete implementation lives in internal/system; consumers should depend on the System interface defined here.

Index

Constants

View Source 
const (
	HealthOK       = "ok"
	HealthDegraded = "degraded"
	HealthDown     = "down"
)

Health status

View Source 
const (
	SystemStatusHealthy   = "healthy"
	SystemStatusDegraded  = "degraded"
	SystemStatusUnhealthy = "unhealthy"
)

System status

View Source 
const (
	ProxyStatusRunning = "running"
	ProxyStatusStopped = "stopped"
	ProxyStatusUnknown = "unknown"
)

Proxy status

Variables

This section is empty.

Functions

This section is empty.

Types

type AuthDebug 

type AuthDebug struct {
	AgentTokenAgeS      int64  `json:"agent_token_age_s"`
	AgentTokenExpiresIn int64  `json:"agent_token_expires_in_s"`
	BootstrapToken      string `json:"bootstrap_token"`
}

AuthDebug provides debugging information about the authentication system.

type CPUStats added in v0.5.0 

type CPUStats struct {
	User   float64 `json:"user"`
	System float64 `json:"system"`
	Idle   float64 `json:"idle"`
	IOWait float64 `json:"iowait"`
	Steal  float64 `json:"steal"`
}

CPUStats represents CPU usage breakdown.

type CertDebug 

type CertDebug struct {
	NotAfterRFC3339 string `json:"not_after"`
	DaysRemaining   int    `json:"days_remaining"`
}

CertDebug provides debugging information about the instance's public certificate.

type DiskDebugEntry added in v0.4.3 

type DiskDebugEntry struct {
	Filesystem     string `json:"filesystem"`
	Mountpoint     string `json:"mountpoint"`
	SizeBytes      int64  `json:"size_bytes,omitempty"`
	UsedBytes      int64  `json:"used_bytes,omitempty"`
	AvailableBytes int64  `json:"available_bytes,omitempty"`
}

DiskDebugEntry represents disk usage for a single filesystem/mountpoint.

type DoctorResult 

type DoctorResult struct {
	Status string `json:"status"`
	Output string `json:"output"`
	Error  string `json:"error,omitempty"`
}

type FSCacheInterface added in v0.5.0 

type FSCacheInterface interface {
	GetSnapshot() *FSSnapshot
	ListDir(path string, depth, limit int, cursor string) (*FSListResponse, error)
	ReadFile(path string, offset, limit int64) (*FSReadResponse, error)
	WriteFile(req *FSWriteRequest) (*FSOpResponse, error)
	CreateFile(req *FSCreateRequest) (*FSOpResponse, error)
	DeleteFile(req *FSDeleteRequest) (*FSOpResponse, error)
	Watch(path string, recursive bool) error
	Unwatch(path string) error
	SetBroadcaster(broadcaster func(*FSUpdateEvent))
}

FSCacheInterface defines the interface for filesystem cache operations

type FSCreateRequest added in v0.5.0 

type FSCreateRequest struct {
	Path    string `json:"path"`
	Type    string `json:"type"`              // "file" | "dir"
	Content string `json:"content,omitempty"` // for files
	Mode    string `json:"mode,omitempty"`    // e.g. "0644" or "0755"
}

FSCreateRequest - create new file or dir

type FSDeleteRequest added in v0.5.0 

type FSDeleteRequest struct {
	Path      string `json:"path"`
	Recursive bool   `json:"recursive,omitempty"` // for dirs
}

FSDeleteRequest - delete file or dir

type FSHandler added in v0.5.0 

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

FSHandler handles filesystem HTTP requests

func NewFSHandler added in v0.5.0 

func NewFSHandler(cache FSCacheInterface, logger *shared.Logger) *FSHandler

NewFSHandler creates a new filesystem handler

func (*FSHandler) HandleCreate added in v0.5.0 

func (h *FSHandler) HandleCreate(w http.ResponseWriter, r *http.Request)

HandleCreate handles file/directory creation requests POST /system/fs/create

func (*FSHandler) HandleDelete added in v0.5.0 

func (h *FSHandler) HandleDelete(w http.ResponseWriter, r *http.Request)

HandleDelete handles file/directory deletion requests DELETE /system/fs/delete

func (*FSHandler) HandleList added in v0.5.0 

func (h *FSHandler) HandleList(w http.ResponseWriter, r *http.Request)

HandleList handles directory listing requests GET /system/fs?path=/var/lib&depth=1&limit=100&cursor=...

func (*FSHandler) HandleRead added in v0.5.0 

func (h *FSHandler) HandleRead(w http.ResponseWriter, r *http.Request)

HandleRead handles file read requests GET /system/fs/read?path=/var/lib/file.txt&offset=0&limit=1048576

func (*FSHandler) HandleUnwatch added in v0.5.0 

func (h *FSHandler) HandleUnwatch(w http.ResponseWriter, r *http.Request)

HandleUnwatch handles directory unwatch requests POST /system/fs/unwatch

func (*FSHandler) HandleWatch added in v0.5.0 

func (h *FSHandler) HandleWatch(w http.ResponseWriter, r *http.Request)

HandleWatch handles directory watch requests POST /system/fs/watch

func (*FSHandler) HandleWrite added in v0.5.0 

func (h *FSHandler) HandleWrite(w http.ResponseWriter, r *http.Request)

HandleWrite handles file write requests PUT /system/fs/write

type FSListRequest added in v0.5.0 

type FSListRequest struct {
	Path   string `json:"path"`
	Depth  int    `json:"depth"`            // default 1
	Limit  int    `json:"limit"`            // default 100, max 500
	Cursor string `json:"cursor,omitempty"` // for pagination
}

FSListRequest is the HTTP request for lazy directory expansion

type FSListResponse added in v0.5.0 

type FSListResponse struct {
	Node       FSNode `json:"node"`
	NextCursor string `json:"next_cursor,omitempty"`
	HasMore    bool   `json:"has_more"`
}

FSListResponse is the HTTP response for directory listing

type FSNode added in v0.5.0 

type FSNode struct {
	Path      string    `json:"path"`
	Name      string    `json:"name"`
	Type      string    `json:"type"` // "file" | "dir" | "symlink"
	SizeBytes int64     `json:"size_bytes"`
	ModTime   time.Time `json:"mod_time,omitempty"`

	// Permissions
	Mode  string `json:"mode"`  // e.g. "drwxr-xr-x"
	Owner string `json:"owner"` // username
	Group string `json:"group"` // group name
	UID   int    `json:"uid"`
	GID   int    `json:"gid"`

	// Computed permission flags for the agent's effective user
	Readable   bool `json:"readable"`
	Writable   bool `json:"writable"`
	Executable bool `json:"executable"`

	// Tree structure
	Children   []FSNode `json:"children,omitempty"`
	Truncated  bool     `json:"truncated,omitempty"`
	ChildCount int      `json:"child_count,omitempty"`
}

FSNode represents a filesystem entry with permissions

type FSOpResponse added in v0.5.0 

type FSOpResponse struct {
	Success bool   `json:"success"`
	Path    string `json:"path"`
	Error   string `json:"error,omitempty"`
}

FSOpResponse - generic response for write/create/delete

type FSReadRequest added in v0.5.0 

type FSReadRequest struct {
	Path   string `json:"path"`
	Offset int64  `json:"offset,omitempty"` // for large files
	Limit  int64  `json:"limit,omitempty"`  // max bytes to read (default 1MB)
}

FSReadRequest - read file contents

type FSReadResponse added in v0.5.0 

type FSReadResponse struct {
	Path      string `json:"path"`
	Content   string `json:"content"`  // base64 for binary, utf8 for text
	Encoding  string `json:"encoding"` // "base64" | "utf8"
	Size      int64  `json:"size"`
	Truncated bool   `json:"truncated"`
}

FSReadResponse - file content response

type FSSnapshot added in v0.5.0 

type FSSnapshot struct {
	GeneratedAt time.Time `json:"generated_at"`
	Roots       []FSNode  `json:"roots"`
	Stale       bool      `json:"stale,omitempty"`
}

FSSnapshot is the bounded tree sent in WS updates

type FSUnwatchRequest added in v0.5.0 

type FSUnwatchRequest struct {
	Path string `json:"path"`
}

FSUnwatchRequest - request to stop watching a directory

type FSUpdateEvent added in v0.5.0 

type FSUpdateEvent struct {
	Type      string    `json:"type"` // "created" | "modified" | "deleted" | "renamed"
	Path      string    `json:"path"`
	Node      *FSNode   `json:"node,omitempty"`     // present for created/modified
	OldPath   string    `json:"old_path,omitempty"` // present for renamed
	Timestamp time.Time `json:"timestamp"`
}

FSUpdateEvent represents a filesystem change event

type FSWatchRequest added in v0.5.0 

type FSWatchRequest struct {
	Path      string `json:"path"`
	Recursive bool   `json:"recursive"` // watch subdirectories
}

FSWatchRequest - request to start watching a directory

type FSWriteRequest added in v0.5.0 

type FSWriteRequest struct {
	Path     string `json:"path"`
	Content  string `json:"content"`
	Encoding string `json:"encoding"`       // "base64" | "utf8"
	Mode     string `json:"mode,omitempty"` // e.g. "0644", uses default if empty
}

FSWriteRequest - write/overwrite file

type HelloAckV1 added in v0.4.2 

type HelloAckV1 struct {
	Schema          string    `json:"schema"`
	Accept          bool      `json:"accept"`
	Reason          string    `json:"reason,omitempty"`
	FeaturesEnabled []string  `json:"features_enabled,omitempty"`
	ServerTime      time.Time `json:"server_time"`
}

HelloAckV1 is sent by base to acknowledge the agent hello.

type HelloV1 added in v0.4.2 

type HelloV1 struct {
	Schema           string            `json:"schema"`
	InstanceID       string            `json:"instance_id"`
	BuildInfo        version.BuildInfo `json:"build_info"`
	Platform         PlatformInfo      `json:"platform"`
	Capabilities     []string          `json:"capabilities,omitempty"`
	SchemasSupported []string          `json:"schemas_supported,omitempty"`
}

HelloV1 is sent by the agent when establishing a WebSocket connection.

type InstallRequest 

type InstallRequest struct {
	Version string `json:"version"`
	Token   string `json:"token,omitempty"`
}

InstallRequest is used to request an installation of dployr.

type LoadAverage added in v0.5.0 

type LoadAverage struct {
	Load1  float64 `json:"load1"`
	Load5  float64 `json:"load5"`
	Load15 float64 `json:"load15"`
}

LoadAverage represents system load averages.

type MemoryStats added in v0.5.0 

type MemoryStats struct {
	Total       uint64  `json:"total_bytes"`
	Used        uint64  `json:"used_bytes"`
	Free        uint64  `json:"free_bytes"`
	Available   uint64  `json:"available_bytes"`
	UsedPercent float64 `json:"used_percent"`
	SwapTotal   uint64  `json:"swap_total_bytes"`
	SwapUsed    uint64  `json:"swap_used_bytes"`
	SwapFree    uint64  `json:"swap_free_bytes"`
}

MemoryStats represents memory usage in bytes.

type Mode 

type Mode string

Mode represents the current mode. "ready" – normal operation, syncer active. "updating" – in the middle of an update/installation cycle. 

const (
	ModeReady    Mode = "ready"
	ModeUpdating Mode = "updating"
)

type ModeStatus 

type ModeStatus struct {
	Mode Mode `json:"mode"`
}

ModeStatus describes the current daemon mode.

type PlatformInfo added in v0.4.2 

type PlatformInfo struct {
	OS   string `json:"os"`
	Arch string `json:"arch"`
}

PlatformInfo describes the runtime platform of the agent.

type ProcessInfo added in v0.5.0 

type ProcessInfo struct {
	PID        int32   `json:"pid"`
	User       string  `json:"user"`
	Command    string  `json:"command"`
	CPUPercent float64 `json:"cpu_percent"`
	MemPercent float32 `json:"mem_percent"`
	RSS        int64   `json:"rss_bytes"`
	VMS        int64   `json:"vms_bytes"`
	State      string  `json:"state"`
}

ProcessInfo represents a single process's resource usage.

type RebootRequest added in v0.4.10 

type RebootRequest struct {
	Force bool `json:"force,omitempty"`
}

RebootRequest is used to request a system reboot.

type RebootResponse added in v0.4.10 

type RebootResponse struct {
	Status  string `json:"status"`
	Message string `json:"message"`
}

RebootResponse is returned after initiating a system reboot.

type RegisterInstanceRequest 

type RegisterInstanceRequest struct {
	Claim      string `json:"claim"`
	InstanceID string `json:"instance_id"`
	Issuer     string `json:"issuer"`
	Audience   string `json:"audience"`
}

RegisterInstanceRequest is used to request a registration of an instance.

type RegistrationStatus 

type RegistrationStatus struct {
	Registered bool `json:"registered"`
}

RegistrationStatus reports whether the instance has been registered

type RequestDomainRequest 

type RequestDomainRequest struct {
	Token string `json:"token"`
}

RequestDomainRequest is used to request a domain for an instance.

type RequestDomainResponse 

type RequestDomainResponse struct {
	Success    bool   `json:"success"`
	InstanceID string `json:"instanceId,omitempty"`
	Domain     string `json:"domain,omitempty"`
	Issuer     string `json:"issuer,omitempty"`
	Audience   string `json:"audience,omitempty"`
}

RequestDomainResponse is returned after requesting a domain for an instance.

type RestartRequest added in v0.4.8 

type RestartRequest struct {
	Force bool `json:"force,omitempty"`
}

RestartRequest is used to request a system restart.

type RestartResponse added in v0.4.8 

type RestartResponse struct {
	Status  string `json:"status"`
	Message string `json:"message"`
}

RestartResponse is returned after initiating a system restart.

type ServiceHandler 

type ServiceHandler struct {
	Svc System
}

func NewServiceHandler 

func NewServiceHandler(s System) *ServiceHandler

func (*ServiceHandler) GetInfo 

func (h *ServiceHandler) GetInfo(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) GetMode 

func (h *ServiceHandler) GetMode(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) Install 

func (h *ServiceHandler) Install(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) Reboot added in v0.4.10 

func (h *ServiceHandler) Reboot(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) RegisterInstance 

func (h *ServiceHandler) RegisterInstance(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) Registered 

func (h *ServiceHandler) Registered(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) RequestDomain 

func (h *ServiceHandler) RequestDomain(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) Restart added in v0.4.8 

func (h *ServiceHandler) Restart(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) RunDoctor 

func (h *ServiceHandler) RunDoctor(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) SetMode 

func (h *ServiceHandler) SetMode(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) SystemStatus 

func (h *ServiceHandler) SystemStatus(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) Tasks 

func (h *ServiceHandler) Tasks(w http.ResponseWriter, r *http.Request)

func (*ServiceHandler) UpdateBootstrapToken 

func (h *ServiceHandler) UpdateBootstrapToken(w http.ResponseWriter, r *http.Request)

type SetModeRequest 

type SetModeRequest struct {
	Mode Mode `json:"mode"`
}

SetModeRequest is used by the agent to change the daemon mode.

type System 

type System interface {
	// GetInfo returns system information.
	GetInfo(ctx context.Context) (utils.SystemInfo, error)
	// RunDoctor runs the system doctor script and returns its combined output.
	RunDoctor(ctx context.Context) (string, error)
	// Install installs dployr; if version is empty, the latest version is installed.
	Install(ctx context.Context, req InstallRequest) (string, error)
	// SystemStatus returns high-level health information.
	SystemStatus(ctx context.Context) (SystemStatus, error)
	// RequestDomain requests and assigns a new random domain from base to the system.
	RequestDomain(ctx context.Context, req RequestDomainRequest) (RequestDomainResponse, error)
	// RegisterInstance registers the system with the base and assigns an instance id
	RegisterInstance(ctx context.Context, req RegisterInstanceRequest) error
	// GetTasks returns a summary of tasks for the given status (e.g. "pending", "completed").
	GetTasks(ctx context.Context, status string, excludeSystem bool) (TaskSummary, error)
	// GetMode returns the current daemon mode.
	GetMode(ctx context.Context) (ModeStatus, error)
	// SetMode updates the daemon mode.
	SetMode(ctx context.Context, req SetModeRequest) (ModeStatus, error)
	// UpdateBootstrapToken updates the bootstrap token.
	UpdateBootstrapToken(ctx context.Context, req UpdateBootstrapTokenRequest) error
	// IsRegistered returns true if this daemon has been registered with base.
	IsRegistered(ctx context.Context) (RegistrationStatus, error)
	// Restart initiates a system restart after ensuring no tasks are running.
	Restart(ctx context.Context, req RestartRequest) (RestartResponse, error)
	// Reboot initiates an OS reboot.
	Reboot(ctx context.Context, req RebootRequest) (RebootResponse, error)
}

System defines an interface for system operations.

type SystemDebug 

type SystemDebug struct {
	WS     WSDebug               `json:"ws"`
	Tasks  TasksDebug            `json:"tasks"`
	Auth   *AuthDebug            `json:"auth,omitempty"`
	Cert   *CertDebug            `json:"cert,omitempty"`
	System *SystemResourcesDebug `json:"system,omitempty"`
}

SystemDebug provides debugging information about the daemon.

type SystemHealth 

type SystemHealth struct {
	Overall string `json:"overall"` // ok|degraded|down
	WS      string `json:"ws"`
	Tasks   string `json:"tasks"`
	Auth    string `json:"auth"`
}

SystemHealth provides high-level health information about the daemon.

type SystemManager 

type SystemManager struct{}

func NewSystemManager 

func NewSystemManager() *SystemManager

type SystemProxyStatus 

type SystemProxyStatus struct {
	Status string `json:"status"`
	Routes int    `json:"routes"`
}

SystemProxyStatus describes proxy health and routing information.

type SystemResourcesDebug added in v0.4.3 

type SystemResourcesDebug struct {
	CPUCount      int              `json:"cpu_count"`
	MemTotalBytes int64            `json:"mem_total_bytes,omitempty"`
	MemUsedBytes  int64            `json:"mem_used_bytes,omitempty"`
	MemFreeBytes  int64            `json:"mem_free_bytes,omitempty"`
	Disks         []DiskDebugEntry `json:"disks,omitempty"`
	Workers       int              `json:"workers,omitempty"`
}

SystemResourcesDebug provides high-level system resource information for debugging.

type SystemStatus 

type SystemStatus struct {
	Status      string             `json:"status"`
	Mode        Mode               `json:"mode"`
	Uptime      string             `json:"uptime"`
	Deployments []store.Deployment `json:"deployments"`
	Services    []store.Service    `json:"services"`
	Apps        []proxy.App        `json:"proxies"`
	Proxy       SystemProxyStatus  `json:"proxy"`
	Health      SystemHealth       `json:"health"`
	Debug       *SystemDebug       `json:"debug,omitempty"`
}

SystemStatus describes high-level health information about the daemon.

type SystemTop added in v0.5.0 

type SystemTop struct {
	Timestamp time.Time     `json:"timestamp"`
	Uptime    uint64        `json:"uptime_seconds"`
	LoadAvg   LoadAverage   `json:"load_avg"`
	CPU       CPUStats      `json:"cpu"`
	Memory    MemoryStats   `json:"memory"`
	Tasks     TaskStats     `json:"tasks"`
	Processes []ProcessInfo `json:"processes"`
}

SystemTop represents a snapshot of system resource usage (like `top` output).

type TaskStats added in v0.5.0 

type TaskStats struct {
	Total    int `json:"total"`
	Running  int `json:"running"`
	Sleeping int `json:"sleeping"`
	Stopped  int `json:"stopped"`
	Zombie   int `json:"zombie"`
}

TaskStats represents task/process counts by state.

type TaskSummary 

type TaskSummary struct {
	Count int `json:"count"`
}

TaskSummary represents a simple count of tasks for a given status.

type TasksDebug 

type TasksDebug struct {
	Inflight          int    `json:"inflight"`
	DoneUnsent        int    `json:"done_unsent"`
	LastTaskID        string `json:"last_task_id,omitempty"`
	LastTaskStatus    string `json:"last_task_status,omitempty"`
	LastTaskDurMs     int64  `json:"last_task_dur_ms,omitempty"`
	LastTaskAtRFC3339 string `json:"last_task_at,omitempty"`
}

TasksDebug provides debugging information about the task queue.

type TopCollectorInterface added in v0.5.0 

type TopCollectorInterface interface {
	Collect(ctx context.Context, sortBy string, limit int) (*SystemTop, error)
	CollectSummary(ctx context.Context) (*SystemTop, error)
}

TopCollectorInterface defines the interface for collecting system top data.

type TopHandler added in v0.5.0 

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

TopHandler handles /system/top requests.

func NewTopHandler added in v0.5.0 

func NewTopHandler(collector TopCollectorInterface, logger *shared.Logger) *TopHandler

NewTopHandler creates a new TopHandler.

func (*TopHandler) HandleTop added in v0.5.0 

func (h *TopHandler) HandleTop(w http.ResponseWriter, r *http.Request)

HandleTop handles GET /system/top requests.

type TopRequest added in v0.5.0 

type TopRequest struct {
	SortBy string `json:"sort_by"` // "cpu" or "mem"
	Limit  int    `json:"limit"`   // max processes to return
}

TopRequest represents query parameters for the /system/top endpoint.

type UpdateBootstrapTokenRequest 

type UpdateBootstrapTokenRequest struct {
	Token string `json:"token"`
}

UpdateBootstrapTokenRequest is used to bootstrap token

type UpdateV1 added in v0.4.3 

type UpdateV1 struct {
	Schema      string             `json:"schema"`
	Seq         uint64             `json:"seq"`
	Epoch       string             `json:"epoch"`
	Full        bool               `json:"full"`
	InstanceID  string             `json:"instance_id"`
	BuildInfo   version.BuildInfo  `json:"build_info"`
	Platform    PlatformInfo       `json:"platform"`
	Status      string             `json:"status"`
	Mode        Mode               `json:"mode"`
	Uptime      string             `json:"uptime"`
	Deployments []store.Deployment `json:"deployments"`
	Services    []store.Service    `json:"services"`
	Apps        []proxy.App        `json:"proxies"`
	Proxy       SystemProxyStatus  `json:"proxy"`
	Health      SystemHealth       `json:"health"`
	Debug       *SystemDebug       `json:"debug,omitempty"`
	FS          *FSSnapshot        `json:"fs,omitempty"`
	Top         *SystemTop         `json:"top,omitempty"`
}

UpdateV1 represents the status update payload sent from the agent to base. This struct defines the core schema relied upon by clients interacting with the dployr API.

type WSDebug 

type WSDebug struct {
	Connected            bool    `json:"connected"`
	LastConnectAtRFC3339 string  `json:"last_connect_at"`
	ReconnectsSinceStart uint64  `json:"reconnects_since_start"`
	LastError            *string `json:"last_error,omitempty"`
}

WSDebug provides debugging information about the WebSocket connection.

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.