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
- type AddDatabaseUserRequest
- type AddSSHKeyRequest
- type App
- type AppView
- type AuthPatch
- type AuthSettings
- type AuthShare
- type AuthUser
- type AuthUserRequest
- type AuthUserResult
- type BackupDestination
- type BackupInfo
- type BackupJob
- type BackupKey
- type BackupKeyStatus
- type BackupPoint
- type BackupResult
- type BackupRun
- type BackupsOverview
- type BuilderRequest
- type CloneAppRequest
- type ClusterEvent
- type ClusterStatus
- type ClusterTotals
- type ConfigPatch
- type ConfigVars
- type Contact
- type CreateAppRequest
- type CreateBackupDestinationRequest
- type CreateDatabaseRequest
- type CreateEdgeRequest
- type CreateJoinTokenRequest
- type CreateShareRequest
- type CreateVolumeRequest
- type Database
- type DatabaseClient
- type DatabaseExposure
- type DatabaseLink
- type DatabaseQuery
- type DatabaseStats
- type DatabaseUser
- type DatabaseWindow
- type Deploy
- type DeployKey
- type Domains
- type DomainsPatch
- type Edge
- type EdgeAccess
- type Error
- type Event
- type ExposeDatabaseRequest
- type External
- type ExternalRequest
- type Firewall
- type FirewallBan
- type FirewallCounts
- type FirewallPatch
- type FirewallReport
- type FirewallSettings
- type FirewallSite
- type FirewallSlowed
- type FirewallSlowedAddr
- type FirewallSuspect
- type FirewallUnban
- type FirewallUnbanned
- type Formation
- type GitRepo
- type Instance
- type InstanceSpec
- type InstanceStatus
- type InstanceView
- type InstanceVolume
- type JoinRequest
- type JoinResponse
- type JoinToken
- type Latency
- type LatencyStats
- type LatencyWindow
- type LinkDatabaseRequest
- type LogOptions
- type MoveVolumeRequest
- type NetLink
- type NetProbe
- type NetProbeResult
- type NetSinkResult
- type NetTest
- type NetTestProgress
- type NetTestRequest
- type NetTests
- type Node
- type NodeIdentity
- type NodeMetrics
- type NodeState
- type NodeStatus
- type NodeUpdate
- type NodeView
- type Peer
- type PingStats
- type Process
- type Properties
- type ProxyActivity
- type ProxyAuth
- type ProxyFirewall
- type ProxyRoute
- type ProxyShare
- type ProxyState
- type ProxyStream
- type ProxyUser
- type Rebalance
- type RebalanceMove
- type RebalanceRequest
- type RegistryLogin
- type RegistryLoginRequest
- type Release
- type RenameAppRequest
- type Request
- type ResizeVolumeRequest
- type ResourceLimits
- type ResourceSize
- type Resources
- type RestoreSpec
- type RestoreVolumeRequest
- type RouteAuth
- type SSHKey
- type ScaleRequest
- type SetPropertyRequest
- type SetVolumeBackupRequest
- type UpdateFailure
- type UpdateOrder
- type Version
- type Volume
- type VolumeBackups
- type VolumeMount
- type VolumeMove
- type VolumeOldCopy
- type VolumeProtection
- type VolumeSpec
- type VolumeStatus
Constants ¶
const ( CheckTCP = "tcp" CheckUp = "up" )
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 )
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 )
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.
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.
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.
const ( DefaultFirewallNotFound = 20 DefaultFirewallWindow = 10 * time.Minute DefaultFirewallBan = time.Hour DefaultFirewallRate = 50 DefaultFirewallBurst = 300 )
The firewall's defaults (firewall:set changes them).
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).
const ( EventLog = "log" EventRequest = "request" EventDone = "done" StatusRunning = "running" StatusSucceeded = "succeeded" StatusFailed = "failed" )
const FeatureFirewall = "firewall"
FeatureFirewall is reported by agents whose proxy has the firewall (ProxyState.Firewall), from v0.8.14.
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.
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.
const FeatureStreams = "streams"
FeatureStreams is reported by agents whose proxy carries TCP routes (ProxyState.Streams), from v0.8.10.
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.
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.
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.
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.
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.
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.
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 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"`
// 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 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 ¶
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 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 ¶
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 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 CreateJoinTokenRequest ¶
type CreateShareRequest ¶
type CreateShareRequest struct {
}
type CreateVolumeRequest ¶
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 ¶
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 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 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 InstanceVolume ¶
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 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 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 ¶ added in v0.8.19
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
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 NodeMetrics ¶
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.
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 {
}
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 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 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 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 *
}
RouteAuth is the login in front of one app.
type ScaleRequest ¶
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 ¶
UpdateFailure is a node saying an update order failed.
type UpdateOrder ¶
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 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 ¶
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 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.