api

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package api is what the shinyctl command and shinyctl-api say to each other over api.sock: the requests and replies of apply, restart, stop, delete and status as JSON, and the client that sends them.

Index

Constants

View Source
const PIDHeader = "X-Shinyctl-Pid"

PIDHeader is the response header in which shinyctl-api names its process.

Variables

This section is empty.

Functions

func Healthy

func Healthy(socketPath string) (pid int, ok bool)

Healthy asks shinyctl-api at socketPath whether it is up: /healthz answers only once it is, not merely listening. It also returns the process that answered (0 from a shinyctl-api that doesn't say), which tells a daemon just started from another that was already there.

Types

type AppStatus

type AppStatus struct {
	Name         string       `json:"name"`
	Host         string       `json:"host"`
	Port         int          `json:"port"`
	Stopped      bool         `json:"stopped"`
	Replicas     int          `json:"replicas"`
	WarmReplicas int          `json:"warm-replicas"`
	Copies       []CopyStatus `json:"copies"`

	// RestartPolicy is the app's restart-policy as it applies (always,
	// on-failure or never), so a copy the policy leaves down can be explained.
	RestartPolicy string `json:"restart-policy,omitempty"`

	// NotServed is why the load balancer leaves the app's port unserved (it
	// is taken by another program or another app), or empty. The copies may
	// be running fine behind it.
	NotServed string `json:"not-served,omitempty"`

	// NotStarted is why the app's copies aren't started: its port is taken
	// by another program. It is not a crash and is not counted as one.
	NotStarted string `json:"not-started,omitempty"`
}

AppStatus is one app's current, observed status, with a row per copy.

type ApplyResponse

type ApplyResponse struct {
	Action  reconcile.ActionType `json:"action"`
	Message string               `json:"message"`
}

ApplyResponse is shinyctl-api's response to the spec-carrying POSTs — /apply, /stop, /delete and /restart: which action it took, and a line for the CLI to print.

func Apply

func Apply(socketPath string, spec manifest.AppSpec, opts Options) (ApplyResponse, error)

Apply sends spec to shinyctl-api's /apply endpoint over the Unix socket at socketPath and returns its response.

func Delete

func Delete(socketPath string, spec manifest.AppSpec) (ApplyResponse, error)

Delete sends spec to shinyctl-api's /delete endpoint over the Unix socket at socketPath, asking it to stop the app, forget it entirely, and remove its state file.

func Restart

func Restart(socketPath string, spec manifest.AppSpec, opts Options) (ApplyResponse, error)

Restart sends spec to shinyctl-api's /restart endpoint over the Unix socket at socketPath, asking it to start the app's copies again from spec next to the running ones, which then drain (or stop, with opts.Now).

func Stop

func Stop(socketPath string, spec manifest.AppSpec) (ApplyResponse, error)

Stop sends spec to shinyctl-api's /stop endpoint over the Unix socket at socketPath, asking it to stop the app and not restart it until re-applied.

type CopyStatus

type CopyStatus struct {
	Copy       int       `json:"copy"`
	Role       string    `json:"role,omitempty"` // "active", "warm", "draining", or empty when the load balancer doesn't list it
	PID        int       `json:"pid"`
	StartedAt  time.Time `json:"started-at"`
	Alive      bool      `json:"alive"`
	Ready      bool      `json:"ready"`
	CrashCount int       `json:"crash-count"`

	// GaveUp says the copy is not running and the restart policy brings it
	// back no more (until the next apply or restart).
	GaveUp bool `json:"gave-up,omitempty"`

	// Outdated says the copy runs a previous version, draining or not.
	Outdated bool `json:"outdated,omitempty"`

	// DrainEndsAt is when drain-timeout ends the copy's drain at the latest;
	// zero when it isn't draining.
	DrainEndsAt time.Time `json:"drain-ends-at,omitzero"`

	// SkipDrain says the copy stops without draining once it is replaced
	// (--now).
	SkipDrain bool `json:"skip-drain,omitempty"`

	// RSSBytes is the resident memory of the copy's main process; zero when
	// it isn't running or couldn't be measured.
	RSSBytes int64 `json:"rss-bytes,omitempty"`

	// Sessions is the number of requests open to the copy through the load
	// balancer (a Shiny session is one open WebSocket); nil when unknown.
	Sessions *int `json:"sessions,omitempty"`
}

CopyStatus is one copy of an app: what state.json recorded about its process, plus live IsAlive/IsReady checks, not just a mirror of the file. Ready is purely informational (it never drives a restart decision, only Alive does): the copy's process accepts connections, and the load balancer serves the app's port and lists the copy (for a process from before the load balancer, whether its own port accepts).

type Options

type Options struct {
	Now bool // stop what is replaced or no longer wanted at once instead of draining it
}

Options are what a request asks for beyond the spec. They travel as query parameters, so a shinyctl-api that doesn't know one ignores it and does the ordinary thing.

type StatusResponse

type StatusResponse struct {
	Apps []AppStatus `json:"apps"`

	// BalancerRSS is the resident memory of the load balancer's process;
	// zero when it couldn't be measured.
	BalancerRSS int64 `json:"balancer-rss-bytes,omitempty"`

	// BalancerStarting says the load balancer is being started or replaced by
	// one of another build, and does not answer for the moment.
	BalancerStarting bool `json:"balancer-starting,omitempty"`
}

StatusResponse is shinyctl-api's response to a GET /status request: every app in its registry — applied at some point and not deleted since, across shinyctl-api's own restarts.

func Status

func Status(socketPath string) (StatusResponse, error)

Status fetches shinyctl-api's /status endpoint over the Unix socket at socketPath.

Jump to

Keyboard shortcuts

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