types

package
v0.8.22 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package types defines the JSON shapes of the Jokku HTTP API. The server and every client (CLI, git hook, future GUI) share them.

Index

Constants

View Source
const (
	CheckTCP = "tcp"
	CheckUp  = "up"
)
View Source
const (
	VolumeOwner    = "owner"    // the disk lives here
	VolumeIncoming = "incoming" // copy the disk from From
	VolumePrevious = "previous" // moved away; keep the old copy until the new node has the disk
	VolumeDestroy  = "destroy"  // delete the disk
	// VolumeStale: the volume was restored onto another node while this one
	// was down. Its disk here may hold newer writes, so it is kept aside
	// (.stale), never used.
	VolumeStale   = "stale"
	VolumeDiscard = "discard" // delete the copy kept aside
)
View Source
const (
	VolumeReady     = "ready"
	VolumeMissing   = "missing"
	VolumeMoved     = "moved"
	VolumeCopying   = "copying"
	VolumeSynced    = "synced"
	VolumeReceived  = "received"
	VolumeRestored  = "restored"
	VolumeFailed    = "failed" // a restore that could not download its backup
	VolumeDestroyed = "destroyed"
	VolumeKept      = "kept"      // the old copy is kept aside
	VolumeDiscarded = "discarded" // the old copy is gone
)
View Source
const (
	StreamPostgres = "postgres" // TLS, after Postgres's SSLRequest or directly (PG17's sslnegotiation=direct)
	StreamTLS      = "tls"      // TLS from the first byte (rediss://)
	StreamPlain    = "plain"    // passed through untouched
)

Stream protocols.

View Source
const (
	AuthPassword = "password" // one shared password (or PIN) for the app
	AuthUsers    = "users"    // the cluster's users, each with a password and optionally a TOTP code
)

Login modes.

View Source
const (
	UpdateWaiting = "waiting"  // its turn is coming (once it is up, if it is down)
	UpdateRunning = "updating" // updating now
	UpdateFailed  = "failed"   // its update failed; the cluster's update stopped there
	UpdateOnHold  = "on-hold"  // waiting, but the cluster's update stopped at a failure
	UpdateByHand  = "by-hand"  // its jokku is too old to update itself
)

NodeUpdate states.

View Source
const (
	DefaultFirewallNotFound = 20
	DefaultFirewallWindow   = 10 * time.Minute
	DefaultFirewallBan      = time.Hour
	DefaultFirewallRate     = 50
	DefaultFirewallBurst    = 300
)

The firewall's defaults (firewall:set changes them).

View Source
const (
	FirewallBanned  = "banned"  // the address is banned: 403
	FirewallLimited = "limited" // too many requests a second: 429
)

What the firewall did to a request, in its access log line (Request.Firewall).

View Source
const (
	EventLog     = "log"
	EventRequest = "request"
	EventDone    = "done"

	StatusRunning   = "running"
	StatusSucceeded = "succeeded"
	StatusFailed    = "failed"
)
View Source
const FeatureFirewall = "firewall"

FeatureFirewall is reported by agents whose proxy has the firewall (ProxyState.Firewall), from v0.8.14.

View Source
const FeatureNetTest = "nettest"

FeatureNetTest is reported by agents that take part in network tests: they answer pings and take throughput from other nodes, and test a link when the control node asks.

View Source
const FeatureRelay = "relay"

FeatureRelay is reported by agents whose proxy relays an edge's requests (ProxyState.Edges), and, on an edge, sends them through the nodes' proxies (ProxyRoute.Relayed), from v0.8.7. An edge reaches nodes without it straight at their instances, as before.

View Source
const FeatureStreams = "streams"

FeatureStreams is reported by agents whose proxy carries TCP routes (ProxyState.Streams), from v0.8.10.

View Source
const FeatureUpdate = "update"

FeatureUpdate is reported by agents that update jokku when told to (NodeState.Update), from v0.8.5. Older ones are updated by hand.

View Source
const FeatureVolumes = "volumes"

FeatureVolumes is reported by agents that can hold volumes. Instances with volumes are only placed on nodes reporting it, so an agent a release behind never starts one without its disk.

View Source
const (
	// HeaderActor names who is making the request (an SSH key name, a token
	// name, "root"). Informational in v1.
	HeaderActor = "X-Jokku-Actor"
)

Header names used by the API.

View Source
const KindExternal = "external"

KindExternal is an app Jokku doesn't run: a service elsewhere on the network (Home Assistant on the LAN, say) that its proxies route a domain to. The external: commands manage it.

View Source
const ProtocolVersion = 1

ProtocolVersion is the control <-> agent protocol. The control node rejects agents speaking another version, with a message to update. Their state polls still work, and carry an update order for agents that can update themselves, so keep NodeState.Update readable by older agents.

View Source
const RoleEdge = "edge"

RoleEdge is an edge node: a public machine that only receives traffic for the cluster's domains and sends it over the mesh to the nodes behind it, which dial it. It runs no apps.

View Source
const (
	VolumeLocal = "local"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AddDatabaseUserRequest

type AddDatabaseUserRequest struct {
	Name     string `json:"name"`
	ReadOnly bool   `json:"read_only,omitempty"`
}

AddDatabaseUserRequest adds a login to a database that reads and writes its data (only reads when ReadOnly), with a password Jokku makes.

type AddSSHKeyRequest

type AddSSHKeyRequest struct {
	Name      string `json:"name"`
	PublicKey string `json:"public_key"`
}

type App

type App struct {
	Name string `json:"name"`
	// Kind is "" for an app deployed from code, the engine of a database
	// (postgres, mysql, redis), which the db: commands manage, or
	// KindExternal for a service Jokku routes to but doesn't run.
	Kind    string `json:"kind,omitempty"`
	Locked  bool   `json:"locked"`
	Stopped bool   `json:"stopped"` // ps:stop
	// AsleepSince is when the app went to sleep for want of requests
	// (ps:set sleep-after); nil while it's awake.
	AsleepSince    *time.Time `json:"asleep_since,omitempty"`
	CreatedAt      time.Time  `json:"created_at"`
	CurrentRelease int        `json:"current_release,omitempty"`
	DeploySource   string     `json:"deploy_source,omitempty"`
}

type AppView

type AppView struct {
	Name      string    `json:"name"`
	Kind      string    `json:"kind,omitempty"` // a database's engine
	Release   int       `json:"release"`
	Stopped   bool      `json:"stopped"`
	Asleep    bool      `json:"asleep,omitempty"`
	Locked    bool      `json:"locked"`
	Domains   []string  `json:"domains"`
	Healthy   int       `json:"healthy"`
	Wanted    int       `json:"wanted"`
	Deploy    *Deploy   `json:"deploy,omitempty"` // most recent
	CreatedAt time.Time `json:"created_at"`
	// Links are the apps a database is linked to.
	Links []DatabaseLink `json:"links,omitempty"`
	// Target is an external app's URL, and Via the server that reaches it.
	Target string `json:"target,omitempty"`
	Via    string `json:"via,omitempty"`
}

type AuthPatch

type AuthPatch struct {
	Mode        string    `json:"mode,omitempty"`     // off, password or users
	Password    string    `json:"password,omitempty"` // for mode password
	Users       *[]string `json:"users,omitempty"`
	AllowIPs    *[]string `json:"allow_ips,omitempty"`
	BypassPaths *[]string `json:"bypass_paths,omitempty"`
	// Global settings.
	LoginDomain *string `json:"login_domain,omitempty"`
	SessionDays int     `json:"session_days,omitempty"`
}

AuthPatch changes an app's login: the fields that are set.

type AuthSettings

type AuthSettings struct {
	App         string   `json:"app,omitempty"`
	Mode        string   `json:"mode"` // off, password or users
	HasPassword bool     `json:"has_password,omitempty"`
	Users       []string `json:"users,omitempty"` // allowed users; empty with mode users allows every user
	AllowIPs    []string `json:"allow_ips,omitempty"`
	BypassPaths []string `json:"bypass_paths,omitempty"`
	Shares      int      `json:"shares,omitempty"`
	// Global settings.
	LoginDomain string `json:"login_domain,omitempty"`
	SessionDays int    `json:"session_days,omitempty"`
}

AuthSettings is an app's login (http-auth), or the cluster's settings for logins (app "").

type AuthShare

type AuthShare struct {
	ID        string    `json:"id"`
	App       string    `json:"app"`
	Note      string    `json:"note,omitempty"`
	ExpiresAt time.Time `json:"expires_at"`
	CreatedAt time.Time `json:"created_at"`
	// URL is the link, returned only when the share is created.
	URL string `json:"url,omitempty"`
}

type AuthUser

type AuthUser struct {
	Name      string    `json:"name"`
	TOTP      bool      `json:"totp"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type AuthUserRequest

type AuthUserRequest struct {
	Name     string `json:"name,omitempty"`
	Password string `json:"password,omitempty"`
	TOTP     *bool  `json:"totp,omitempty"`
}

AuthUserRequest creates a user, or changes their password. TOTP turns a second factor on (a new secret, returned once) or, false, off.

type AuthUserResult

type AuthUserResult struct {
	AuthUser
	TOTPSecret string `json:"totp_secret,omitempty"`
	TOTPURI    string `json:"totp_uri,omitempty"` // otpauth://, for authenticator apps
}

AuthUserResult is a user, with their new TOTP secret when one was made.

type BackupDestination

type BackupDestination struct {
	Name            string    `json:"name"`
	Endpoint        string    `json:"endpoint"` // https://host[:port]; http:// for a local test server
	Region          string    `json:"region,omitempty"`
	Bucket          string    `json:"bucket"`
	AccessKeyID     string    `json:"access_key_id"`
	SecretAccessKey string    `json:"secret_access_key,omitempty"`
	Encrypt         bool      `json:"encrypt"`
	CreatedAt       time.Time `json:"created_at"`
	// BacksUpCluster, when a destination was just added, says it was made
	// where the cluster itself is backed up (there was nowhere yet).
	BacksUpCluster bool `json:"backs_up_cluster,omitempty"`
}

BackupDestination is an S3-compatible bucket that volumes are backed up to. The secret only travels to the node doing a backup or restore; lists leave it out.

type BackupInfo

type BackupInfo struct {
	Name      string    `json:"name"`
	Time      time.Time `json:"time"`
	Size      int64     `json:"size,omitempty"`      // the disk's size
	NewBytes  int64     `json:"new_bytes,omitempty"` // what it added to the bucket
	NewBlocks int       `json:"new_blocks,omitempty"`
}

BackupInfo is one backup in a bucket. The sizes are known for backups this cluster made.

type BackupJob

type BackupJob struct {
	Volume      string            `json:"volume"` // the volume's ID
	App         string            `json:"app"`
	Name        string            `json:"name"`   // the volume's name
	Backup      string            `json:"backup"` // the backup's name
	Destination BackupDestination `json:"destination"`
	Path        string            `json:"path"`
	Key         string            `json:"key,omitempty"`
	// Instance, when a running VM has the disk attached, is that VM, and
	// MountPath where the volume is in it: writes there are paused for the
	// moment the backup is taken.
	Instance  string `json:"instance,omitempty"`
	MountPath string `json:"mount_path,omitempty"`
}

BackupJob asks the node holding a volume's disk to back it up.

type BackupKey

type BackupKey struct {
	Key   string `json:"key"`
	ID    string `json:"id"`
	Saved bool   `json:"saved"`
}

BackupKey is the key that encrypts the cluster's backups. Saved says the user confirmed keeping a copy; encrypted backups wait until then.

type BackupKeyStatus

type BackupKeyStatus struct {
	ID    string `json:"id"`
	Saved bool   `json:"saved"`
}

type BackupPoint

type BackupPoint struct {
	At       time.Time `json:"at"`
	Status   string    `json:"status"`
	NewBytes int64     `json:"new_bytes"`
}

BackupPoint is one recent backup attempt.

type BackupResult

type BackupResult struct {
	Name      string `json:"name"`
	Size      int64  `json:"size"`
	Blocks    int    `json:"blocks"`
	NewBlocks int    `json:"new_blocks"`
	NewBytes  int64  `json:"new_bytes"`
}

BackupResult is what one backup stored.

type BackupRun

type BackupRun struct {
	Name       string    `json:"name"`
	Status     string    `json:"status"` // running | succeeded | failed
	Error      string    `json:"error,omitempty"`
	StartedAt  time.Time `json:"started_at"`
	FinishedAt time.Time `json:"finished_at,omitzero"`
}

BackupRun is one attempt at a backup.

type BackupsOverview

type BackupsOverview struct {
	Destinations  []BackupDestination `json:"destinations"`
	Key           *BackupKeyStatus    `json:"key,omitempty"`
	Cluster       *VolumeBackups      `json:"cluster,omitempty"`
	ClusterRecent []BackupPoint       `json:"cluster_recent,omitempty"`
	Volumes       []VolumeProtection  `json:"volumes"`
}

BackupsOverview is everything about backups at once, for jokku top: where they go, the key (not its text), the cluster's own backups, and every volume, backed up or not.

type BuilderRequest

type BuilderRequest struct {
	Type string `json:"type"`
	File string `json:"file,omitempty"`
}

BuilderRequest switches how an app is built: from a Dockerfile or a compose file (File, relative to the build dir; empty for the default).

type CloneAppRequest

type CloneAppRequest struct {
	NewName string `json:"new_name"`
}

type ClusterEvent

type ClusterEvent struct {
	ID      int64     `json:"id"`
	At      time.Time `json:"at"`
	Kind    string    `json:"kind"` // deploy, instance, node
	App     string    `json:"app,omitempty"`
	Node    string    `json:"node,omitempty"`
	Message string    `json:"message"`
}

ClusterEvent is something that happened: a deploy, a crash, a node going down.

type ClusterStatus

type ClusterStatus struct {
	Version   string         `json:"version"`
	Control   string         `json:"control"`
	Nodes     []NodeView     `json:"nodes"`
	Apps      []AppView      `json:"apps"`
	Instances []InstanceView `json:"instances"`
	Events    []ClusterEvent `json:"events"`
	At        time.Time      `json:"at"`
	Totals    ClusterTotals  `json:"totals"`
}

ClusterStatus is the whole picture, for "jokku top" and dashboards.

type ClusterTotals

type ClusterTotals struct {
	NodesReady       int `json:"nodes_ready"`
	Nodes            int `json:"nodes"`
	Apps             int `json:"apps"`
	InstancesHealthy int `json:"instances_healthy"`
	Instances        int `json:"instances"` // wanted, of apps that are running
	// InstancesAsleep and InstancesStopped are the instances of apps
	// asleep (ps:set sleep-after) and stopped (ps:stop): off on purpose,
	// so not in Instances.
	InstancesAsleep  int `json:"instances_asleep,omitempty"`
	InstancesStopped int `json:"instances_stopped,omitempty"`
}

type ConfigPatch

type ConfigPatch struct {
	Set   map[string]string `json:"set,omitempty"`
	Unset []string          `json:"unset,omitempty"`
	Clear bool              `json:"clear,omitempty"`
}

ConfigPatch changes config vars. Unset runs before Set; Clear removes everything first. Changes apply to running instances on the next restart (POST /v1/apps/{app}/ps/restart).

type ConfigVars

type ConfigVars struct {
	Vars    map[string]string `json:"vars"`
	Changed bool              `json:"changed,omitempty"` // on PATCH: whether anything changed
}

type Contact

type Contact struct {
	// HeardAgo is how long since it last heard from the control node; -1 if
	// it hasn't since it started.
	HeardAgoSeconds float64 `json:"heard_ago_seconds"`
}

Contact is what a node's agent says about its contact with the control node.

type CreateAppRequest

type CreateAppRequest struct {
	Name string `json:"name"`
}

type CreateBackupDestinationRequest

type CreateBackupDestinationRequest struct {
	Name            string `json:"name"`
	Endpoint        string `json:"endpoint"`
	Region          string `json:"region,omitempty"`
	Bucket          string `json:"bucket"`
	AccessKeyID     string `json:"access_key_id"`
	SecretAccessKey string `json:"secret_access_key"`
	NoEncrypt       bool   `json:"no_encrypt,omitempty"`
}

type CreateDatabaseRequest

type CreateDatabaseRequest struct {
	Name         string `json:"name"`
	Image        string `json:"image,omitempty"`
	ImageVersion string `json:"image_version,omitempty"`
	SizeMB       int    `json:"size_mb,omitempty"`
	MemoryMB     int    `json:"memory_mb,omitempty"`
}

CreateDatabaseRequest creates a database: Image (default the engine's official one) at ImageVersion (default its current major version), with a SizeMB volume and MemoryMB of memory (defaults when 0).

type CreateEdgeRequest

type CreateEdgeRequest struct {
	Name    string `json:"name"`
	Address string `json:"address"` // its public address (IP or DNS name), where the nodes behind it reach it
}

type CreateJoinTokenRequest

type CreateJoinTokenRequest struct {
	TTLSeconds int  `json:"ttl_seconds,omitempty"` // default one hour
	Reusable   bool `json:"reusable,omitempty"`    // for autoscaling groups
}

type CreateShareRequest

type CreateShareRequest struct {
	TTLSeconds int    `json:"ttl_seconds"`
	Note       string `json:"note,omitempty"`
}

type CreateVolumeRequest

type CreateVolumeRequest struct {
	Name   string `json:"name"`
	Type   string `json:"type,omitempty"`    // default local
	SizeMB int    `json:"size_mb,omitempty"` // default 10 GiB
}

type Database

type Database struct {
	Engine    string    `json:"engine"`
	Name      string    `json:"name"`
	App       string    `json:"app"`    // the app it runs as
	Image     string    `json:"image"`  // e.g. postgres:17
	Status    string    `json:"status"` // running, starting, crashed, stopped, deploying or none
	Node      string    `json:"node,omitempty"`
	MemoryMB  int       `json:"memory_mb,omitempty"`
	Host      string    `json:"host"` // where apps reach it, host:port
	URL       string    `json:"url"`  // with its password
	CreatedAt time.Time `json:"created_at"`

	Links   []DatabaseLink `json:"links"`
	Volume  *Volume        `json:"volume,omitempty"`
	Backups *VolumeBackups `json:"backups,omitempty"`
	// Vars are its config vars (passwords among them), for connecting from
	// the CLI; only a single database's info has them.
	Vars map[string]string `json:"vars,omitempty"`
	// Exposed is how clients outside reach it (db:<engine>:expose); nil
	// while they can't.
	Exposed *DatabaseExposure `json:"exposed,omitempty"`
	// Stats is what the control node has seen inside it: connections,
	// queries and how long they take.
	Stats *DatabaseStats `json:"stats,omitempty"`
}

Database is a database Jokku runs (db:<engine>:info).

type DatabaseClient

type DatabaseClient struct {
	App      string `json:"app,omitempty"`      // the app whose instance connects
	Instance string `json:"instance,omitempty"` // web.1
	Via      string `json:"via,omitempty"`      // the node whose proxy carries clients outside
	Local    bool   `json:"local,omitempty"`    // from inside the database's VM
	Addr     string `json:"addr,omitempty"`
	User     string `json:"user,omitempty"`
	Count    int    `json:"count"`
	Active   int    `json:"active"`
}

DatabaseClient is a database's connections from one place as one user: an app's instance, the proxies (clients outside, db:<engine>:expose), or the database's own VM (db:<engine>:connect).

type DatabaseExposure

type DatabaseExposure struct {
	Host  string   `json:"host"`
	Port  int      `json:"port"`
	Allow []string `json:"allow,omitempty"` // the client addresses let in; empty: any
	LAN   bool     `json:"lan,omitempty"`
	URL   string   `json:"url"` // with its password
}

DatabaseExposure is how clients outside reach a database: at Host:Port, through the ingress nodes' and edges' proxies, or only the ingress nodes' when LAN.

type DatabaseLink struct {
	App string `json:"app"`
	Var string `json:"var"`
}

DatabaseLink is an app a database is linked to, and the config var on it that holds the database's URL.

type DatabaseQuery

type DatabaseQuery struct {
	Query   string  `json:"query"`
	Calls   uint64  `json:"calls"`
	TotalMS float64 `json:"total_ms"`
	MeanMS  float64 `json:"mean_ms"`
}

DatabaseQuery is a statement and how long it has taken.

type DatabaseStats

type DatabaseStats struct {
	App    string    `json:"app"`
	Engine string    `json:"engine"`
	Name   string    `json:"name"`
	Node   string    `json:"node,omitempty"`
	At     time.Time `json:"at,omitzero"` // the last look; zero before the first
	// Error is why the last look failed, and Note something missing, in a
	// sentence ("query times start at its next restart").
	Error string `json:"error,omitempty"`
	Note  string `json:"note,omitempty"`

	Connections    int              `json:"connections"`
	MaxConnections int              `json:"max_connections"`
	Active         int              `json:"active"`             // running a query now; -1 when the engine can't tell
	MaxUsed        int              `json:"max_used,omitempty"` // the most at once since it started, when the engine keeps it
	Clients        []DatabaseClient `json:"clients,omitempty"`

	// Per is what a query is: "query", "transaction" (Postgres without
	// pg_stat_statements) or "command" (Redis). HitsAre is what the hit
	// rate counts: "cache" (reads from memory rather than disk) or
	// "keys" (Redis: keys found).
	Per     string         `json:"per,omitempty"`
	HitsAre string         `json:"hits_are,omitempty"`
	Minute  DatabaseWindow `json:"minute"`
	Hour    DatabaseWindow `json:"hour"`
	Day     DatabaseWindow `json:"day"`

	Slowest    []DatabaseQuery `json:"slowest,omitempty"` // Postgres and MySQL: by total time, since its statistics started
	Users      []DatabaseUser  `json:"users,omitempty"`
	MemoryUsed uint64          `json:"memory_used,omitempty"` // Redis, bytes
	MemoryMax  uint64          `json:"memory_max,omitempty"`  // 0: no limit
}

DatabaseStats is a look inside a database ("jokku top", db:<engine>:info): its connections now, and its queries over the last minute, hour and day. The control node takes a look at each running database every few seconds and keeps the history in memory, so it starts over when it restarts.

type DatabaseUser

type DatabaseUser struct {
	Name      string `json:"name"`
	Access    string `json:"access"`
	Password  string `json:"password,omitempty"`
	URL       string `json:"url,omitempty"`
	PublicURL string `json:"public_url,omitempty"`
}

DatabaseUser is a login of a database's. Access is "all" (schema changes included), "read-write", "read-only" or "other" (privileges Jokku didn't set); Password and URLs are known for the users Jokku added.

type DatabaseWindow

type DatabaseWindow struct {
	Seconds   float64 `json:"seconds"` // how much of the span there are looks for
	Queries   uint64  `json:"queries"`
	PerSecond float64 `json:"per_second"`
	// P50, P95 and P99 are how long queries took inside the database, in
	// milliseconds, from engines that keep a histogram (MySQL, Redis);
	// AvgMS is the mean, which every engine has. 0 without queries.
	P50   float64 `json:"p50_ms,omitempty"`
	P95   float64 `json:"p95_ms,omitempty"`
	P99   float64 `json:"p99_ms,omitempty"`
	AvgMS float64 `json:"avg_ms,omitempty"`
	// HitRate is the share of reads served from memory (or keys found),
	// 0 to 1; -1 without reads.
	HitRate float64 `json:"hit_rate"`
}

DatabaseWindow is a database's queries over a span of time.

type Deploy

type Deploy struct {
	ID         int64      `json:"id"`
	App        string     `json:"app"`
	Source     string     `json:"source"` // git | archive | image | rebuild
	SourceRef  string     `json:"source_ref,omitempty"`
	Status     string     `json:"status"` // pending | building | deploying | succeeded | failed
	Error      string     `json:"error,omitempty"`
	Actor      string     `json:"actor,omitempty"`
	Release    int        `json:"release,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
}

type DeployKey

type DeployKey struct {
	PublicKey string `json:"public_key"`
}

type Domains

type Domains struct {
	App     []string `json:"app"`
	Global  []string `json:"global"`
	Vhosts  []string `json:"vhosts"` // effective hostnames the proxy will serve
	Enabled bool     `json:"enabled"`
}

type DomainsPatch

type DomainsPatch struct {
	Add    []string `json:"add,omitempty"`
	Remove []string `json:"remove,omitempty"`
	Set    []string `json:"set,omitempty"`
	Clear  bool     `json:"clear,omitempty"`
}

DomainsPatch changes an app's (or the global) domains. Exactly one field should be set.

type Edge

type Edge struct {
	Node
	Version string `json:"version,omitempty"` // the jokku it runs (or, before it's installed, should)
	// Command installs it, on the edge itself; it holds the edge's
	// credentials, so it is only returned when the edge is created.
	Command string `json:"command,omitempty"`
	// Bundle is the credentials inside Command, for "jokku setup --edge".
	Bundle string `json:"bundle,omitempty"`
}

Edge is an edge node, with how to install it.

type EdgeAccess

type EdgeAccess struct {
	Edges   []string `json:"edges"`             // the edges' mesh subnets
	Allow   []string `json:"allow,omitempty"`   // IP:port they may reach
	Targets []string `json:"targets,omitempty"` // IPs outside the cluster reached for them (masqueraded)
	Control bool     `json:"control,omitempty"` // this is the control node: edges may reach its API
}

EdgeAccess is what edge nodes may reach on or through a node over the mesh. An edge faces the internet, so it gets only what its routes need: the web ports of this node's instances, the external-app targets this node forwards to, and on the control node, the API.

type Error

type Error struct {
	Error string `json:"error"`
}

Error is the body of every non-2xx response.

type Event

type Event struct {
	Type    string   `json:"type"` // log | request | done
	Message string   `json:"message,omitempty"`
	Request *Request `json:"request,omitempty"`
	Status  string   `json:"status,omitempty"` // on done: succeeded | failed
	Error   string   `json:"error,omitempty"`
	// Backup, on a node's done event for a backup, is what it stored.
	Backup *BackupResult `json:"backup,omitempty"`
}

Event is one line of a streamed (application/x-ndjson) response.

type ExposeDatabaseRequest

type ExposeDatabaseRequest struct {
	Domain string   `json:"domain"`
	Port   int      `json:"port,omitempty"`
	Allow  []string `json:"allow,omitempty"`
	LAN    bool     `json:"lan,omitempty"`
}

ExposeDatabaseRequest lets clients outside reach a database at Domain:Port (Port 0: the engine's own), from the addresses in Allow (none: any). LAN keeps it on your network: the edges don't carry it, and Allow defaults to the private ranges (cluster.LANRanges).

type External

type External struct {
	Name      string    `json:"name"`
	URL       string    `json:"url"` // http(s)://IP:port
	Via       string    `json:"via"`
	Insecure  bool      `json:"insecure,omitempty"` // an https target's certificate isn't checked
	Domains   []string  `json:"domains"`
	Auth      string    `json:"auth,omitempty"` // its login mode, if it has one
	CreatedAt time.Time `json:"created_at"`
}

External is an external app: its domains are routed to URL, reached through Via (the node that forwards edge traffic to it).

type ExternalRequest

type ExternalRequest struct {
	Name     string `json:"name,omitempty"`
	URL      string `json:"url,omitempty"`
	Via      string `json:"via,omitempty"`
	Insecure *bool  `json:"insecure,omitempty"`
}

ExternalRequest creates an external app, or with PATCH changes the fields that are set.

type Firewall

type Firewall struct {
	Settings FirewallSettings  `json:"settings"`
	Bans     []FirewallBan     `json:"bans"` // newest first
	Watching []FirewallSuspect `json:"watching,omitempty"`
	// Slowed is the addresses answered 429 in the last hour, the most first.
	Slowed []FirewallSlowedAddr `json:"slowed,omitempty"`
	// Minute, Hour and Day add up every proxy's counts and every app's.
	Minute FirewallCounts `json:"minute"`
	Hour   FirewallCounts `json:"hour"`
	Day    FirewallCounts `json:"day"`
	Sites  []FirewallSite `json:"sites,omitempty"`
	// Nodes are the proxies that report, and Missing those a visitor can
	// reach that run a release without the firewall.
	Nodes   []string `json:"nodes,omitempty"`
	Missing []string `json:"missing,omitempty"`
}

Firewall is what the control node knows of the firewall (firewall:report, jokku top).

type FirewallBan

type FirewallBan struct {
	Addr    string    `json:"addr"` // an IPv4 address, or an IPv6 /64
	App     string    `json:"app,omitempty"`
	Host    string    `json:"host,omitempty"`
	Paths   []string  `json:"paths,omitempty"` // the last pages not found before the ban
	At      time.Time `json:"at"`
	Until   time.Time `json:"until"`
	Blocked uint64    `json:"blocked"` // requests refused since
	// Nodes are the proxies that banned it (filled in by the control node).
	Nodes []string `json:"nodes,omitempty"`
}

FirewallBan is an address a proxy refuses until Until.

type FirewallCounts

type FirewallCounts struct {
	Requests uint64 `json:"requests"`  // let through
	Blocked  uint64 `json:"blocked"`   // from banned addresses (403)
	Limited  uint64 `json:"limited"`   // over the rate (429)
	NotFound uint64 `json:"not_found"` // let through and not found, counting toward a ban
	Bans     uint64 `json:"bans"`      // addresses banned
}

FirewallCounts is what a proxy did with an app's requests.

func (*FirewallCounts) Add

func (c *FirewallCounts) Add(o FirewallCounts)

type FirewallPatch

type FirewallPatch struct {
	Enabled  *bool     `json:"enabled,omitempty"`
	NotFound *int      `json:"not_found,omitempty"`
	Window   *string   `json:"window,omitempty"`
	Ban      *string   `json:"ban,omitempty"`
	Rate     *int      `json:"rate,omitempty"`
	Burst    *int      `json:"burst,omitempty"`
	Allow    *[]string `json:"allow,omitempty"`
}

FirewallPatch changes the firewall: for every app, or (Enabled only) one.

type FirewallReport

type FirewallReport struct {
	Bans     []FirewallBan             `json:"bans"`
	Counts   map[string]FirewallCounts `json:"counts,omitempty"`   // by app; "" for hosts no app serves
	Limited  map[string]FirewallSlowed `json:"limited,omitempty"`  // by address
	Watching []FirewallSuspect         `json:"watching,omitempty"` // the most pages not found first
}

FirewallReport is what a proxy tells the control node every few seconds: the bans it has now, what it did since it last said, and the addresses getting close to a ban.

type FirewallSettings

type FirewallSettings struct {
	Enabled    bool     `json:"enabled"`
	NotFound   int      `json:"not_found"`
	Window     string   `json:"window"` // a duration: 10m
	Ban        string   `json:"ban"`
	Rate       int      `json:"rate"`
	Burst      int      `json:"burst"`
	Allow      []string `json:"allow,omitempty"`
	OffForApps []string `json:"off_for_apps,omitempty"`
}

FirewallSettings is the firewall's rules, and where it's off.

type FirewallSite

type FirewallSite struct {
	App    string         `json:"app"` // "" for hosts no app serves
	Minute FirewallCounts `json:"minute"`
	Hour   FirewallCounts `json:"hour"`
	Day    FirewallCounts `json:"day"`
}

FirewallSite is one app's counts.

type FirewallSlowed

type FirewallSlowed struct {
	App     string    `json:"app,omitempty"`
	Limited uint64    `json:"limited"` // requests answered 429
	Last    time.Time `json:"last"`
}

FirewallSlowed is an address that went over the rate.

type FirewallSlowedAddr

type FirewallSlowedAddr struct {
	Addr string `json:"addr"`
	FirewallSlowed
}

type FirewallSuspect

type FirewallSuspect struct {
	Addr     string    `json:"addr"`
	App      string    `json:"app,omitempty"`
	NotFound int       `json:"not_found"` // within the window
	Last     time.Time `json:"last"`
	Node     string    `json:"node,omitempty"`
}

FirewallSuspect is an address getting pages not found, not (yet) as many as a ban takes.

type FirewallUnban

type FirewallUnban struct {
	Addr string `json:"addr"`
}

FirewallUnban lifts an address's bans.

type FirewallUnbanned

type FirewallUnbanned struct {
	Banned bool `json:"banned"`
}

FirewallUnbanned says whether the address had a ban.

type Formation

type Formation struct {
	Processes []Process `json:"processes"`
}

type GitRepo

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

type Instance

type Instance struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"` // web.1
	Release   int       `json:"release"`
	Node      string    `json:"node"`
	IP        string    `json:"ip"`
	Port      int       `json:"port"`
	CPUs      int       `json:"cpus"`
	MemoryMB  int       `json:"memory_mb"`
	State     string    `json:"state"`   // pending | starting | healthy | crashed | failed
	Desired   string    `json:"desired"` // running | stopped
	Restarts  int       `json:"restarts"`
	StartedAt time.Time `json:"started_at"`
}

Instance is one running (or starting, or retiring) microVM.

type InstanceSpec

type InstanceSpec struct {
	ID          string `json:"id"`
	App         string `json:"app"`
	Process     string `json:"process"` // web.1
	ProcessType string `json:"process_type"`
	Run         bool   `json:"run"`

	Artifact       string `json:"artifact"` // file name under artifacts/
	ArtifactSHA256 string `json:"artifact_sha256,omitempty"`
	ArtifactSize   int64  `json:"artifact_size,omitempty"`

	IP       string `json:"ip"`
	Port     int    `json:"port"`
	CPUs     int    `json:"cpus"`
	MemoryMB int    `json:"memory_mb"`

	Argv     []string `json:"argv"`
	Env      []string `json:"env"`
	User     string   `json:"user,omitempty"`
	WorkDir  string   `json:"workdir,omitempty"`
	Hostname string   `json:"hostname"`

	// MaxRestarts is how often a crashed instance is restarted: -1 for
	// always, 0 for never.
	MaxRestarts int `json:"max_restarts"`

	// Check is how the instance proves it is up: CheckTCP (it accepts
	// connections on Port) or CheckUp (it stays up a few seconds). Empty is
	// the original rule: tcp for the web process, up for the others.
	Check string `json:"check,omitempty"`
	// StopTimeout is the seconds the app gets after StopSignal (default
	// SIGTERM) before it is killed; 0 means the default, 10.
	StopTimeout int    `json:"stop_timeout,omitempty"`
	StopSignal  string `json:"stop_signal,omitempty"`

	// Volumes are mounted into the VM. Each is listed in the node's Volumes
	// as owned by it; the instance waits while one is still being copied
	// here.
	Volumes []InstanceVolume `json:"volumes,omitempty"`
}

InstanceSpec is one microVM this node should hold. Run is false while the app is stopped (the VM is kept off, its files kept). Instances not listed are stopped and removed.

type InstanceStatus

type InstanceStatus struct {
	ID          string    `json:"id"`
	State       string    `json:"state"` // pulling | syncing | starting | healthy | crashed | failed | stopped
	HealthyOnce bool      `json:"healthy_once"`
	Restarts    int       `json:"restarts"`
	StartedAt   time.Time `json:"started_at"`
	CPUPercent  float64   `json:"cpu_percent"` // of one vCPU, so up to 100 * vCPUs
	MemoryMB    int       `json:"memory_mb"`
}

type InstanceView

type InstanceView struct {
	Instance
	App        string  `json:"app"`
	CPUPercent float64 `json:"cpu_percent"`
	MemoryUsed int     `json:"memory_used_mb"`
}

type InstanceVolume

type InstanceVolume struct {
	ID   string `json:"id"`
	Path string `json:"path"`
}

InstanceVolume mounts a volume at Path in an instance.

type JoinRequest

type JoinRequest struct {
	Protocol  int    `json:"protocol"`
	Version   string `json:"version"`
	Token     string `json:"token"`
	Name      string `json:"name"`
	PublicKey string `json:"public_key"` // WireGuard
	Endpoint  string `json:"endpoint"`   // host:port other nodes reach its WireGuard on
	Arch      string `json:"arch"`
	CPUs      int    `json:"cpus"`
	MemoryMB  int    `json:"memory_mb"`
}

JoinRequest is sent by a new node to the control node.

type JoinResponse

type JoinResponse struct {
	Node       NodeIdentity `json:"node"`
	NodeToken  string       `json:"node_token"`  // authenticates the agent to the control node
	AgentToken string       `json:"agent_token"` // authenticates the control node to the agent
}

JoinResponse gives the new node its identity and credentials.

type JoinToken

type JoinToken struct {
	Token     string    `json:"token"`
	ExpiresAt time.Time `json:"expires_at"`
	Command   string    `json:"command"` // the one-liner to run on the new server
}

type Latency

type Latency struct {
	Hour LatencyWindow `json:"hour"`
	Day  LatencyWindow `json:"day"`
	// Missing are the nodes that didn't answer (down, or a release
	// behind), whose requests aren't counted.
	Missing []string `json:"missing,omitempty"`
}

Request is one HTTP request handled by a node's proxy: the router lines in "jokku logs" and the traffic view in "jokku top". Latency is how long requests took over the last hour and day, from every node's proxy: overall and by app ("" for requests no app served).

type LatencyStats

type LatencyStats struct {
	Requests uint64  `json:"requests"`
	P50      float64 `json:"p50_ms"`
	P95      float64 `json:"p95_ms"`
}

type LatencyWindow

type LatencyWindow struct {
	LatencyStats
	Apps map[string]LatencyStats `json:"apps,omitempty"`
}

type LinkDatabaseRequest

type LinkDatabaseRequest struct {
	App       string `json:"app"`
	Alias     string `json:"alias,omitempty"`
	NoRestart bool   `json:"no_restart,omitempty"`
}

LinkDatabaseRequest links a database to App, setting <Alias>_URL (default the engine's DATABASE_URL or REDIS_URL) on it, and restarting it unless NoRestart.

type LogOptions

type LogOptions struct {
	Tail    int    `json:"tail"`
	Follow  bool   `json:"follow"`
	Process string `json:"process,omitempty"` // "web" or "web.1"
}

LogOptions select app log lines.

type MoveVolumeRequest

type MoveVolumeRequest struct {
	Node string `json:"node"`
}
type NetLink struct {
	From string `json:"from"`
	To   string `json:"to"`
	// Mbps is the TCP throughput From sent at, as To received it.
	Mbps float64   `json:"mbps"`
	Ping PingStats `json:"ping"`
	// Error says why the link couldn't be measured (or only in part).
	Error string `json:"error,omitempty"`
}

NetLink is what From measured towards To.

type NetProbe added in v0.8.19

type NetProbe struct {
	Target  string  `json:"target"`
	Seconds float64 `json:"seconds"`
	Pings   int     `json:"pings"`
}

NetProbe asks a node's agent to measure its link to another node's agent, at Target (host:port on the mesh).

type NetProbeResult added in v0.8.19

type NetProbeResult struct {
	Mbps      float64   `json:"mbps"`
	Ping      PingStats `json:"ping"`
	PingError string    `json:"ping_error,omitempty"`
	Error     string    `json:"error,omitempty"`
}

NetProbeResult is what an agent measured for a NetProbe.

type NetSinkResult added in v0.8.19

type NetSinkResult struct {
	Bytes   int64   `json:"bytes"`
	Seconds float64 `json:"seconds"`
}

NetSinkResult is what a node took in from a throughput test.

type NetTest added in v0.8.19

type NetTest struct {
	Started  time.Time `json:"started"`
	Finished time.Time `json:"finished"`
	Seconds  float64   `json:"seconds"` // how long each link was loaded
	Nodes    []string  `json:"nodes"`
	Links    []NetLink `json:"links"`
	// Skipped are the nodes left out, and why ("not ready", "runs v0.8.18").
	Skipped map[string]string `json:"skipped,omitempty"`
	// Stopped says why the test ended before testing every link.
	Stopped string `json:"stopped,omitempty"`
}

NetTest is one test of the network between the cluster's nodes (not its edges): every ordered pair in turn, over the mesh, so each link is measured alone and the way apps use it.

type NetTestProgress added in v0.8.19

type NetTestProgress struct {
	Started time.Time `json:"started"`
	Done    int       `json:"done"`  // links measured
	Total   int       `json:"total"` // links to measure
	From    string    `json:"from"`  // the link being measured
	To      string    `json:"to"`
	// Test is what was measured so far.
	Test *NetTest `json:"test"`
}

NetTestProgress is a test that is running.

type NetTestRequest added in v0.8.19

type NetTestRequest struct {
	Seconds float64 `json:"seconds,omitempty"`
}

NetTestRequest starts a test. Seconds is how long each link is loaded (default 3).

type NetTests added in v0.8.19

type NetTests struct {
	Running *NetTestProgress `json:"running,omitempty"`
	Tests   []NetTest        `json:"tests"`
}

NetTests is the network test that is running, if any, and the latest finished ones, newest first.

type Node

type Node struct {
	Name        string    `json:"name"`
	Role        string    `json:"role"`   // control | worker | edge
	Status      string    `json:"status"` // ready | down | draining
	Address     string    `json:"address"`
	MeshIP      string    `json:"mesh_ip"`
	Subnet      string    `json:"subnet"`
	Arch        string    `json:"arch"`
	CPUs        int       `json:"cpus"`
	MemoryMB    int       `json:"memory_mb"`
	Schedulable bool      `json:"schedulable"`
	Ingress     bool      `json:"ingress"`
	LastSeen    time.Time `json:"last_seen"`
	CreatedAt   time.Time `json:"created_at"`
}

type NodeIdentity

type NodeIdentity struct {
	Name        string `json:"name"`
	Role        string `json:"role,omitempty"` // control | worker | edge
	Subnet      string `json:"subnet"`         // e.g. 10.210.2.0/24
	MeshIP      string `json:"mesh_ip"`        // e.g. 10.210.2.1
	ClusterCIDR string `json:"cluster_cidr"`
}

type NodeMetrics

type NodeMetrics struct {
	CPUs         int     `json:"cpus"`
	CPUPercent   float64 `json:"cpu_percent"` // whole machine, 0-100
	Load1        float64 `json:"load1"`
	MemoryMB     int     `json:"memory_mb"`
	MemoryUsedMB int     `json:"memory_used_mb"`
	DiskMB       int     `json:"disk_mb"`
	DiskFreeMB   int     `json:"disk_free_mb"`
}

type NodeState

type NodeState struct {
	ETag      string         `json:"etag"` // changes whenever anything below changes
	Version   string         `json:"version"`
	Node      NodeIdentity   `json:"node"`
	Peers     []Peer         `json:"peers"`
	Instances []InstanceSpec `json:"instances"`
	Volumes   []VolumeSpec   `json:"volumes,omitempty"`
	Proxy     *ProxyState    `json:"proxy,omitempty"` // nil on non-ingress nodes
	// DNS is the cluster's internal names (<process>.<app>.internal,
	// <app>.internal) and their instances' addresses.
	DNS map[string][]string `json:"dns,omitempty"`
	// EdgeAccess is what the cluster's edge nodes may reach on or through
	// this node; nil without edges, and on edges themselves.
	EdgeAccess *EdgeAccess `json:"edge_access,omitempty"`
	// Update tells the node to update jokku; nil the rest of the time.
	Update *UpdateOrder `json:"update,omitempty"`
}

NodeState is everything one node's agent needs, computed by the control node from the store. Agents long-poll for it and cache it, so a node keeps running its last known state while the control node is unreachable.

type NodeStatus

type NodeStatus struct {
	Protocol  int              `json:"protocol"`
	Version   string           `json:"version"`
	ETag      string           `json:"etag"`              // the state it is applying
	CanRun    string           `json:"can_run,omitempty"` // why microVMs cannot run here; empty if they can
	Features  []string         `json:"features,omitempty"`
	Metrics   NodeMetrics      `json:"metrics"`
	Instances []InstanceStatus `json:"instances"`
	Volumes   []VolumeStatus   `json:"volumes,omitempty"`
	// UpdateFailed is set once an update order has failed here.
	UpdateFailed *UpdateFailure `json:"update_failed,omitempty"`
}

NodeStatus is what an agent reports every few seconds.

type NodeUpdate

type NodeUpdate struct {
	To    string     `json:"to"`
	State string     `json:"state"` // one of the NodeUpdate states below
	Since *time.Time `json:"since,omitempty"`
	Error string     `json:"error,omitempty"`
}

NodeUpdate is one node's part in updating the cluster to a version.

type NodeView

type NodeView struct {
	Node
	Version     string      `json:"version"`
	CanRun      string      `json:"can_run,omitempty"`
	Metrics     NodeMetrics `json:"metrics"`
	AllocatedMB int         `json:"allocated_mb"` // memory promised to instances
	Instances   int         `json:"instances"`
	// Update is where the node stands in an update of the cluster; nil when
	// none is asking anything of it.
	Update *NodeUpdate `json:"update,omitempty"`
}

type Peer

type Peer struct {
	Name      string `json:"name"`
	Role      string `json:"role,omitempty"` // RoleEdge for an edge; empty otherwise
	PublicKey string `json:"public_key"`
	// Endpoint is where to reach its WireGuard, host:port. It is empty in an
	// edge's peer list: the nodes behind an edge may sit behind NAT, so they
	// dial it, never the other way round.
	Endpoint string `json:"endpoint,omitempty"`
	Subnet   string `json:"subnet"`
	MeshIP   string `json:"mesh_ip"`
	// Routes are more addresses (IP/32) reached through this peer: the
	// targets of external apps it forwards to. Only edges get them.
	Routes []string `json:"routes,omitempty"`
	// AgentAddr is its agent API, host:port, where nodes ask each other
	// whether they still hear from the control node. Edges have none: they
	// take no part in that vote.
	AgentAddr string `json:"agent_addr,omitempty"`
}

Peer is another node on the WireGuard mesh.

type PingStats added in v0.8.19

type PingStats struct {
	Sent     int     `json:"sent"`
	Received int     `json:"received"`
	Min      float64 `json:"min_ms"`
	Avg      float64 `json:"avg_ms"`
	Max      float64 `json:"max_ms"`
	Jitter   float64 `json:"jitter_ms"` // standard deviation, ping's mdev
}

PingStats are round trips of ICMP echoes, in milliseconds.

func (PingStats) LossPct added in v0.8.19

func (p PingStats) LossPct() float64

LossPct is the share of echoes that got no answer, in percent.

type Process

type Process struct {
	Type     string `json:"type"`
	Quantity int    `json:"quantity"`
	CPUs     int    `json:"cpus"`
	MemoryMB int    `json:"memory_mb"`
}

Process is one process type's formation and size.

type Properties

type Properties struct {
	Plugin   string            `json:"plugin"`
	App      map[string]string `json:"app,omitempty"`
	Global   map[string]string `json:"global"`
	Computed map[string]string `json:"computed,omitempty"`
}

Properties is the report shape for any Dokku-style "<plugin>:set" plugin.

type ProxyActivity

type ProxyActivity struct {
	Active []string `json:"active,omitempty"`
	Wake   []string `json:"wake,omitempty"`
}

ProxyActivity is what a node's proxy tells the control node about apps that sleep when idle: those it handled requests for since it last said, and those a request is waiting to wake.

type ProxyAuth

type ProxyAuth struct {
	Key         string      `json:"key"`                    // signs sessions, base64
	LoginDomain string      `json:"login_domain,omitempty"` // one login page for every domain
	SessionDays int         `json:"session_days"`
	Users       []ProxyUser `json:"users,omitempty"`
}

ProxyAuth is the cluster's login settings, shared by every route that has a login.

type ProxyFirewall

type ProxyFirewall struct {
	NotFound  int `json:"not_found"`  // pages not found within Window that ban an address
	WindowSec int `json:"window_sec"` // seconds
	BanSec    int `json:"ban_sec"`    // how long a ban lasts, in seconds
	Rate      int `json:"rate"`       // requests a second an address may make; 0 for no limit
	Burst     int `json:"burst"`      // and at once
	// Allow is the addresses (CIDRs) never banned or slowed, besides
	// private ones, which never are.
	Allow []string `json:"allow,omitempty"`
	// Unbanned lifts these addresses' bans, each when a proxy first sees it
	// (firewall:unban).
	Unbanned map[string]time.Time `json:"unbanned,omitempty"`
}

ProxyFirewall is the firewall's rules, the same on every proxy.

type ProxyRoute

type ProxyRoute struct {
	App       string   `json:"app"`
	Hosts     []string `json:"hosts"`
	Upstreams []string `json:"upstreams"`
	TLS       bool     `json:"tls"`
	// UpstreamTLS says the upstreams speak HTTPS (an external app's target),
	// and Insecure that their certificates aren't checked.
	UpstreamTLS bool `json:"upstream_tls,omitempty"`
	Insecure    bool `json:"insecure,omitempty"`
	// Auth puts a login in front of the route; nil for none.
	Auth *RouteAuth `json:"auth,omitempty"`
	// Sleeps says the app sleeps when idle (ps:set sleep-after): the proxy
	// tells the control node it is being used, and a request that finds it
	// asleep (no upstreams) wakes it and waits.
	Sleeps bool `json:"sleeps,omitempty"`
	// NoCompress: the app opted out of compression (proxy:set compress
	// false).
	NoCompress bool `json:"no_compress,omitempty"`
	// Relayed, on an edge: the upstreams are nodes' proxies, which pass the
	// request on to an instance and compress the response.
	Relayed bool `json:"relayed,omitempty"`
	// NoFirewall: the app opted out of the firewall (firewall:disable).
	NoFirewall bool `json:"no_firewall,omitempty"`
}

type ProxyShare

type ProxyShare struct {
	ID        string    `json:"id"`
	TokenHash string    `json:"token_hash"` // hex SHA-256 of the token in the link
	ExpiresAt time.Time `json:"expires_at"`
}

ProxyShare is a link that lets anyone holding it in, until it expires.

type ProxyState

type ProxyState struct {
	Routes []ProxyRoute `json:"routes"`
	Email  string       `json:"email,omitempty"`
	// Auth is what routes with a login need: the session key, the users and
	// the login domain. Nil when no route has a login.
	Auth *ProxyAuth `json:"auth,omitempty"`
	// Edges are the edges' mesh subnets, on a node an edge sends requests
	// through: this node's proxy answers them for the edge, compressing
	// before they go back over the mesh.
	Edges []string `json:"edges,omitempty"`
	// Streams are the TCP routes: databases reached from outside
	// (db:<engine>:expose). Only nodes reporting FeatureStreams get them.
	Streams []ProxyStream `json:"streams,omitempty"`
	// Firewall is the firewall's rules; nil when it's off, and for nodes
	// that don't report FeatureFirewall.
	Firewall *ProxyFirewall `json:"firewall,omitempty"`
}

type ProxyStream

type ProxyStream struct {
	App       string   `json:"app"`
	Protocol  string   `json:"protocol"` // StreamPostgres, StreamTLS or StreamPlain
	Host      string   `json:"host"`
	Port      int      `json:"port"`
	Upstreams []string `json:"upstreams"` // IP:port; none while the database isn't running
	// ACME: Host's certificate comes from Let's Encrypt; otherwise from the
	// proxy's own CA, for a name Let's Encrypt can't reach (clients then
	// encrypt without verifying, as sslmode=require does).
	ACME bool `json:"acme,omitempty"`
	// Allow is the client addresses let in (CIDRs); empty lets in any.
	Allow []string `json:"allow,omitempty"`
}

ProxyStream sends the TCP connections for Host on Port to Upstreams. A postgres or tls stream shares its port with the others of its protocol, told apart by the name the client asks for (TLS SNI), and the proxy terminates its TLS; a plain one has its port to itself and passes through as it is (MySQL, whose TLS starts inside its own protocol).

type ProxyUser

type ProxyUser struct {
	Name         string `json:"name"`
	PasswordHash string `json:"password_hash"` // bcrypt
	TOTPSecret   string `json:"totp_secret,omitempty"`
}

type Rebalance added in v0.8.21

type Rebalance struct {
	Moves []RebalanceMove `json:"moves"`
	// Pinned is how many instances with volumes would also have moved with
	// Volumes set; without it they stay where their disks are.
	Pinned int `json:"pinned,omitempty"`
}

Rebalance is what a rebalance moves, or would move.

type RebalanceMove added in v0.8.21

type RebalanceMove struct {
	App      string   `json:"app"`
	Instance string   `json:"instance"` // web.1
	From     string   `json:"from"`
	To       string   `json:"to"`
	MemoryMB int      `json:"memory_mb"`
	Volumes  []string `json:"volumes,omitempty"` // moving with it
}

RebalanceMove is one instance moving to another node.

type RebalanceRequest added in v0.8.21

type RebalanceRequest struct {
	// Volumes also moves instances with volumes, their disks along: each
	// stops for a few seconds while the last changes are copied.
	Volumes bool `json:"volumes,omitempty"`
	DryRun  bool `json:"dry_run,omitempty"` // only say what would move
}

RebalanceRequest asks the control node to spread instances over the nodes (nodes:rebalance).

type RegistryLogin

type RegistryLogin struct {
	Server    string    `json:"server"`
	Username  string    `json:"username"`
	CreatedAt time.Time `json:"created_at"`
}

RegistryLogin lets builds pull from a private registry. The password is never sent back.

type RegistryLoginRequest

type RegistryLoginRequest struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

type Release

type Release struct {
	Version     int       `json:"version"`
	Description string    `json:"description"`
	Current     bool      `json:"current"`
	CreatedAt   time.Time `json:"created_at"`
}

type RenameAppRequest

type RenameAppRequest struct {
	NewName string `json:"new_name"`
}

type Request

type Request struct {
	At           time.Time `json:"at"`
	App          string    `json:"app,omitempty"`  // empty for hosts no app serves
	Node         string    `json:"node,omitempty"` // the node whose proxy received it
	Instance     string    `json:"instance,omitempty"`
	InstanceNode string    `json:"instance_node,omitempty"`
	Upstream     string    `json:"upstream,omitempty"` // IP:port that answered
	Method       string    `json:"method"`
	Host         string    `json:"host"`
	Path         string    `json:"path"`
	Proto        string    `json:"proto,omitempty"`
	Status       int       `json:"status"`
	DurationMS   float64   `json:"duration_ms"`
	Bytes        int64     `json:"bytes"`
	Client       string    `json:"client,omitempty"`
	// Firewall is what the firewall did: FirewallBanned or FirewallLimited,
	// empty when it let the request through.
	Firewall string `json:"firewall,omitempty"`
}

type ResizeVolumeRequest

type ResizeVolumeRequest struct {
	SizeMB int `json:"size_mb"`
}

ResizeVolumeRequest grows a volume. The instance using it picks up the new size when it restarts.

type ResourceLimits

type ResourceLimits struct {
	ProcessType string `json:"process_type,omitempty"`
	CPUs        *int   `json:"cpus,omitempty"`
	MemoryMB    *int   `json:"memory_mb,omitempty"`
}

ResourceLimits sets vCPUs and memory for one process type, or for every process type of the app when ProcessType is empty. Nil fields are left as they are; zero clears the override.

type ResourceSize

type ResourceSize struct {
	CPUs     int `json:"cpus,omitempty"`
	MemoryMB int `json:"memory_mb,omitempty"`
}

type Resources

type Resources struct {
	Default ResourceSize            `json:"default"`
	Process map[string]ResourceSize `json:"process"`
}

type RestoreSpec

type RestoreSpec struct {
	Destination BackupDestination `json:"destination"`
	Path        string            `json:"path"`
	Backup      string            `json:"backup"`
	Key         string            `json:"key,omitempty"`
	// Swap, for a restore on the disk's own node, says the instances using
	// the disk were stopped: the restored copy can replace it.
	Swap bool `json:"swap,omitempty"`
}

RestoreSpec is a backup to make a volume's disk from.

type RestoreVolumeRequest

type RestoreVolumeRequest struct {
	Backup     string `json:"backup,omitempty"`
	Node       string `json:"node,omitempty"`
	SkipBackup bool   `json:"skip_backup,omitempty"`
}

RestoreVolumeRequest restores a volume from one of its backups (the latest without Backup), on Node if given. Unless SkipBackup, the volume is backed up first, so the restore can be undone.

type RouteAuth

type RouteAuth struct {
	Mode         string       `json:"mode"`                    // AuthPassword or AuthUsers
	PasswordHash string       `json:"password_hash,omitempty"` // bcrypt, for AuthPassword
	Users        []string     `json:"users,omitempty"`         // allowed users; empty allows every user
	AllowIPs     []string     `json:"allow_ips,omitempty"`     // CIDRs that skip the login
	BypassPaths  []string     `json:"bypass_paths,omitempty"`  // paths that skip it: exact, or a prefix ending in *
	Shares       []ProxyShare `json:"shares,omitempty"`
}

RouteAuth is the login in front of one app.

type SSHKey

type SSHKey struct {
	Name        string    `json:"name"`
	Fingerprint string    `json:"fingerprint"`
	PublicKey   string    `json:"public_key"`
	CreatedAt   time.Time `json:"created_at"`
}

type ScaleRequest

type ScaleRequest struct {
	Quantities map[string]int `json:"quantities"`
}

type SetPropertyRequest

type SetPropertyRequest struct {
	Value string `json:"value"` // empty unsets
}

type SetVolumeBackupRequest

type SetVolumeBackupRequest struct {
	Destination string `json:"destination"`
	Path        string `json:"path,omitempty"`
	Every       string `json:"every,omitempty"`
	KeepRecent  string `json:"keep_recent,omitempty"`
	KeepDaily   *int   `json:"keep_daily,omitempty"`
	// AutoRestore, "on" (the default) or "off", restores the volume onto
	// another node from its latest backup when its node is down a while.
	AutoRestore string `json:"auto_restore,omitempty"`
}

SetVolumeBackupRequest says where a volume is backed up (Path defaults to jokku/<app>/<volume>), how often (Every, a duration like 15m, 1h or 1d, or "off" for only when asked), and how long backups are kept: every one from the last KeepRecent, and the last of each of the last KeepDaily days. Unset fields keep their current values, or the defaults.

type UpdateFailure

type UpdateFailure struct {
	Attempt string `json:"attempt"`
	Error   string `json:"error"`
}

UpdateFailure is a node saying an update order failed.

type UpdateOrder

type UpdateOrder struct {
	Version string `json:"version"`
	Attempt string `json:"attempt"`
}

UpdateOrder asks a node's agent to update jokku to Version. A node acts on each Attempt once, so one that failed waits for a new order.

type Version

type Version struct {
	Version string `json:"version"`
	Commit  string `json:"commit"`
}

type Volume

type Volume struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	Type   string `json:"type"` // local
	SizeMB int    `json:"size_mb"`
	UsedMB int    `json:"used_mb"`
	// Node holds a local volume's disk; empty until an instance first uses
	// it.
	Node string `json:"node,omitempty"`
	// Disk is the disk image's path on Node.
	Disk   string        `json:"disk,omitempty"`
	Status string        `json:"status"` // new | ready | missing | moving | restoring | destroying
	Move   *VolumeMove   `json:"move,omitempty"`
	Mounts []VolumeMount `json:"mounts"`
	// OldCopy is the disk a node kept after the volume was restored onto
	// another node while it was down: it may hold writes newer than the
	// backup. storage:discard-old-copy deletes it.
	OldCopy *VolumeOldCopy `json:"old_copy,omitempty"`

	CreatedAt time.Time `json:"created_at"`
}

Volume is persistent storage for an app's instances. Type "local" is an ext4 disk on one node: the instance it is mounted in runs on that node, and the disk is copied along when the instance moves (nodes:drain, storage:move).

type VolumeBackups

type VolumeBackups struct {
	Cluster     bool         `json:"cluster,omitempty"`
	App         string       `json:"app"`
	Volume      string       `json:"volume"`
	Destination string       `json:"destination"`
	Path        string       `json:"path"`
	Backups     []BackupInfo `json:"backups,omitempty"` // newest first
	Last        *BackupRun   `json:"last,omitempty"`    // the latest attempt, failed or not
	Succeeded   *BackupRun   `json:"succeeded,omitempty"`

	EverySeconds      int64     `json:"every_seconds"` // 0: only when asked
	KeepRecentSeconds int64     `json:"keep_recent_seconds"`
	KeepDaily         int       `json:"keep_daily"`
	Next              time.Time `json:"next,omitzero"`
	AutoRestore       bool      `json:"auto_restore"`
	// FailoverSeconds is how long its node must be down before it is
	// restored elsewhere.
	FailoverSeconds int64 `json:"failover_seconds,omitempty"`
	// What the backups take up in the bucket, as of the last count plus
	// what backups added since.
	StoredBytes   int64 `json:"stored_bytes"`
	StoredBackups int   `json:"stored_backups"`
}

VolumeBackups is where a volume is backed up, and the backups there. With Cluster, it is the cluster's own backups (App and Volume are empty).

type VolumeMount

type VolumeMount struct {
	ProcessType string `json:"process_type"`
	Path        string `json:"path"`
}

VolumeMount puts a volume at Path in a process type's instances.

type VolumeMove

type VolumeMove struct {
	To       string `json:"to"`
	State    string `json:"state"` // copying | synced (waiting for the instance to stop) | received
	CopiedMB int    `json:"copied_mb"`
	Error    string `json:"error,omitempty"`
}

VolumeMove is a local volume's copy to another node, or a restore from a backup onto To.

type VolumeOldCopy

type VolumeOldCopy struct {
	Node string `json:"node"`
	Disk string `json:"disk"` // where it is on Node, with .stale (or .stale-<time>) at the end
}

type VolumeProtection

type VolumeProtection struct {
	App     string         `json:"app"`
	Volume  string         `json:"volume"`
	Node    string         `json:"node,omitempty"`
	SizeMB  int            `json:"size_mb"`
	UsedMB  int            `json:"used_mb"`
	Status  string         `json:"status"`
	Mounts  []VolumeMount  `json:"mounts"`
	Backups *VolumeBackups `json:"backups,omitempty"`
	Recent  []BackupPoint  `json:"recent,omitempty"` // oldest first
	OldCopy *VolumeOldCopy `json:"old_copy,omitempty"`
}

VolumeProtection is a volume and how it is backed up: Backups is nil when it isn't.

type VolumeSpec

type VolumeSpec struct {
	ID     string `json:"id"`
	App    string `json:"app"`
	Name   string `json:"name"`
	SizeMB int    `json:"size_mb"`
	Role   string `json:"role"` // owner | incoming | previous | destroy

	// Create lets the owner make the disk when it has none: the volume has
	// never held data. Without it a missing disk is an error, not an empty
	// volume.
	Create bool `json:"create,omitempty"`
	// Token authorizes a move: the owner serves the disk to whoever presents
	// it, and the incoming node presents it to From (the owner's agent API,
	// host:port).
	Token string `json:"token,omitempty"`
	From  string `json:"from,omitempty"`
	// Restore, with role incoming, or owner when the disk is restored on
	// its own node, says to make the disk from a backup instead.
	Restore *RestoreSpec `json:"restore,omitempty"`
	// AutoRestore says the volume would be restored onto another node if
	// this one were cut off for long: so this node stops the instances
	// using it when it is, rather than let two copies of the app write.
	AutoRestore bool `json:"auto_restore,omitempty"`
}

VolumeSpec is a local volume's disk this node holds, receives or deletes. Disks are deleted only on an explicit VolumeDestroy, never because a volume stopped being listed.

type VolumeStatus

type VolumeStatus struct {
	ID string `json:"id"`
	// State is ready, missing or moved (handed to the incoming node) for
	// an owner; copying, synced (copied while the instance runs; waiting for
	// it to stop) or received for an incoming node; destroyed once deleted.
	State    string `json:"state"`
	UsedMB   int    `json:"used_mb,omitempty"`
	CopiedMB int    `json:"copied_mb,omitempty"`
	Error    string `json:"error,omitempty"`
	// Restore is how a restore from a backup is going: copying, received
	// (downloaded, waiting for the instance to stop) or restored.
	Restore string `json:"restore,omitempty"`
}

VolumeStatus is what a node reports about a volume it holds.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL