Documentation
¶
Index ¶
- Constants
- func CustomAsService(slug string, def CustomDefinition, reveal bool) catalog.Service
- func CustomImageWarnings(image string) []string
- func CustomVolumeName(slug string) string
- func MakeCustomSlug(name string, taken map[string]bool) string
- func ValidateImage(image string) error
- type CapNotice
- type CustomDefinition
- type CustomEnv
- type CustomEnvView
- type CustomServiceView
- type DeployOptions
- type Manager
- func (m *Manager) CapNotices() []CapNotice
- func (m *Manager) ContainerDrift(ctx context.Context) map[string][]string
- func (m *Manager) Copies() map[string][]runtime.ContainerInfo
- func (m *Manager) CriticalVolumes(slug string) []statebackup.Volume
- func (m *Manager) DeleteCustom(ctx context.Context, slug string) error
- func (m *Manager) DeleteProxy(id int64) error
- func (m *Manager) Deploy(ctx context.Context, slug string, credentials map[string]string) (store.Deployment, error)
- func (m *Manager) DeployImage(ctx context.Context, slug string, credentials map[string]string, image *string) (store.Deployment, error)
- func (m *Manager) DeployProxied(ctx context.Context, slug string, id int64) (ProxiedResult, error)
- func (m *Manager) DeployWith(ctx context.Context, slug string, credentials map[string]string, ...) (store.Deployment, error)
- func (m *Manager) ExecRunning(ctx context.Context, slug string, cmd []string, timeout time.Duration) ([]noderead.Output, error)
- func (m *Manager) HasNativeRuntime() bool
- func (m *Manager) LastRunLogs(ctx context.Context, slug string, lines int) (string, error)
- func (m *Manager) List(ctx context.Context) ([]runtime.ContainerInfo, error)
- func (m *Manager) ListCustom() ([]CustomServiceView, error)
- func (m *Manager) ListProxies() ([]proxies.View, error)
- func (m *Manager) LoadCustom() error
- func (m *Manager) Logs(ctx context.Context, slug string, lines int) (string, error)
- func (m *Manager) LogsCopy(ctx context.Context, slug string, n, lines int) (string, error)
- func (m *Manager) LogsMatching(ctx context.Context, slug string, since time.Duration, match *regexp.Regexp, ...) (string, error)
- func (m *Manager) PlanRemoval(ctx context.Context, slug string) (runtime.RemovalPlan, error)
- func (m *Manager) ProxiedCopies() []runtime.ProxiedCopy
- func (m *Manager) ProxyRefusal(slug string) string
- func (m *Manager) ProxyTick(ctx context.Context) ([]CapNotice, error)
- func (m *Manager) ReadState(ctx context.Context, slug string) ([]byte, []string, error)
- func (m *Manager) Refresh(ctx context.Context) ([]store.Deployment, error)
- func (m *Manager) Register(kind string, provider runtime.Provider)
- func (m *Manager) Remove(ctx context.Context, slug string, deleteData, allowCritical bool) error
- func (m *Manager) RemoveProxied(ctx context.Context, slug string, id int64) error
- func (m *Manager) RequiredCredentialsMet(slug string, credentials map[string]string) bool
- func (m *Manager) ResetProxy(ctx context.Context, id int64) ([]string, error)
- func (m *Manager) Restart(ctx context.Context, slug string) error
- func (m *Manager) SaveCustom(slug string, in CustomDefinition) (CustomServiceView, error)
- func (m *Manager) SaveProxy(ctx context.Context, id int64, values map[string]string) (proxies.View, error)
- func (m *Manager) ScalingLimit(svc catalog.Service) ScalingLimit
- func (m *Manager) ScalingLimits(services []catalog.Service) map[string]ScalingLimit
- func (m *Manager) SignalVars(slug string) map[string]string
- func (m *Manager) Start(ctx context.Context, slug string) error
- func (m *Manager) StartCopy(ctx context.Context, slug string, n int) error
- func (m *Manager) StartProxied(ctx context.Context, slug string, id int64) error
- func (m *Manager) StateFingerprint(ctx context.Context, slug string) (string, error)
- func (m *Manager) Stop(ctx context.Context, slug string) error
- func (m *Manager) StopCopy(ctx context.Context, slug string, n int) error
- func (m *Manager) StopProxied(ctx context.Context, slug string, id int64) error
- func (m *Manager) TestProxy(ctx context.Context, id int64) (ProxyTestResult, error)
- func (m *Manager) ValidateCredentials(slug string, credentials map[string]string) error
- func (m *Manager) ValidateDeploy(slug string, credentials map[string]string) error
- type ProxiedResult
- type ProxyTestResult
- type ScalingLimit
Constants ¶
const (
// CustomDefaultMemLimit is the memory limit a custom service gets when none is given.
CustomDefaultMemLimit = "512m"
)
const CustomUnpinnedWarning = "No version tag: every redeploy pulls whatever the publisher pushed last. Pin a tag or digest."
CustomUnpinnedWarning is shown for an image with no tag, or the latest tag.
const MaxInstances = 10
MaxInstances is the most copies of one service this machine will run. A ceiling against a typo, not a recommendation: on one connection most providers pay for one. The web app uses the same number.
Variables ¶
This section is empty.
Functions ¶
func CustomAsService ¶ added in v0.33.0
func CustomAsService(slug string, def CustomDefinition, reveal bool) catalog.Service
CustomAsService is the catalog-shaped service for a custom definition.
reveal=true puts the real env values in Docker.Env as defaults, for the deploy path only; it must never reach the UI. reveal=false leaves Docker.Env empty, so the deploy form shows no inputs, and is what the catalog overlay holds.
Nothing here can grant anything: no ports, capabilities, devices, network mode, privileged mode, entrypoint or host path. Those fields stay at their zero values.
func CustomImageWarnings ¶ added in v0.33.0
CustomImageWarnings is what is worth telling the user about an image reference.
func CustomVolumeName ¶ added in v0.33.0
CustomVolumeName is the named volume a custom service keeps its data in. Named, not a host path, so it can never reach a host directory, and deterministic, so every redeploy and a change of data path land on the same volume.
func MakeCustomSlug ¶ added in v0.33.0
MakeCustomSlug is a new custom- slug for name that taken does not hold.
Fixed at creation: the container name, the data volume and every record key hang on it, so renaming the service later never moves anything.
A slug never ends in -<digits>. Copy N of a service runs as cashpilot-<slug>-N, so a slug like custom-foo-2 would share its container name with copy 2 of custom-foo, and a deploy of one would replace the other. "Foo 2" becomes custom-foo2, and a second "Foo" becomes custom-foo-v2.
taken must hold every slug ever used, deleted ones included: a reused slug would mount the data volume a deleted service left behind.
func ValidateImage ¶ added in v0.22.0
ValidateImage refuses a typed image that is not an image reference. "" is valid: it means the catalog image.
Types ¶
type CustomDefinition ¶ added in v0.33.0
type CustomDefinition struct {
Name string `json:"name"`
Image string `json:"image"`
Env []CustomEnv `json:"env"`
Command string `json:"command"`
DataPath string `json:"dataPath"`
MemLimit string `json:"memLimit"`
}
CustomDefinition is what the user typed, and what is stored, for one custom service.
func ValidateCustom ¶ added in v0.33.0
func ValidateCustom(in CustomDefinition, previous *CustomDefinition) (CustomDefinition, []string, error)
ValidateCustom is the stored definition for in, and the warnings worth showing. It returns an error meant for the user. previous is the stored definition on an edit, so a secret left blank keeps its value.
type CustomEnv ¶ added in v0.33.0
type CustomEnv struct {
Key string `json:"key"`
Value string `json:"value"`
Secret bool `json:"secret"`
}
CustomEnv is one environment variable of a custom service. Value is the plain value: it is encrypted at rest with the rest of the definition, and a Secret one never leaves the backend again once saved.
type CustomEnvView ¶ added in v0.33.0
type CustomEnvView struct {
Key string `json:"key"`
Value string `json:"value"`
Secret bool `json:"secret"`
IsSet bool `json:"isSet"`
}
CustomEnvView is a variable as the editor may see it: a secret's value is blank, and IsSet says whether one is stored.
type CustomServiceView ¶ added in v0.33.0
type CustomServiceView struct {
Slug string `json:"slug"`
Name string `json:"name"`
Image string `json:"image"`
Env []CustomEnvView `json:"env"`
Command string `json:"command"`
DataPath string `json:"dataPath"`
MemLimit string `json:"memLimit"`
// Volume is the named volume the data path is kept in, "" with no data path.
Volume string `json:"volume"`
Warnings []string `json:"warnings"`
}
CustomServiceView is a custom service as the UI receives it.
type DeployOptions ¶ added in v0.23.0
type DeployOptions struct {
// Image: see DeployImage.
Image *string
// Instances is how many copies of the service to run; see ScalingLimit.
Instances *int
}
DeployOptions are the deploy form's choices beyond the credentials. A nil field means the box was left alone, and the deployment keeps what it already records.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns the runtime provider registry and reconciles it against the store. providers is keyed by runtime kind; defaultKind is the kind used when a deployment or service does not name one — which is every service today, since Docker is the only registered runtime.
func NewManager ¶
NewManager builds a Manager whose registry holds the given provider under defaultRuntimeKind, which also becomes the default kind. The signature is unchanged: callers still pass the single Docker provider, so the app stays single-runtime in behavior until a second provider is registered.
func (*Manager) CapNotices ¶ added in v0.38.0
CapNotices lists every proxy that is capped right now, from the store, so neither a restart nor a missed tick can drop a cap that still holds.
func (*Manager) ContainerDrift ¶ added in v0.30.0
ContainerDrift is, per deployed slug, how its running container differs from what a redeploy would build from the current catalog (see runtime.ShapeDrift). A service with several copies reports its first copy that differs. A runtime that cannot be read reports nothing rather than a guess.
func (*Manager) Copies ¶ added in v0.23.0
func (m *Manager) Copies() map[string][]runtime.ContainerInfo
Copies returns copies 2..N of every service, by slug, as last seen.
func (*Manager) CriticalVolumes ¶ added in v0.31.0
func (m *Manager) CriticalVolumes(slug string) []statebackup.Volume
CriticalVolumes is what the catalog marks irreplaceable for slug, sorted by path, with the catalog's words for what each holds. Empty when it declares nothing or has no entry for slug.
func (*Manager) DeleteCustom ¶ added in v0.33.0
DeleteCustom deletes a custom service's definition. It is refused while this machine runs or records it: remove it from here first, which is also where the user decides about its data volume.
func (*Manager) DeleteProxy ¶ added in v0.38.0
DeleteProxy deletes a proxy that no copy runs through.
func (*Manager) Deploy ¶
func (m *Manager) Deploy(ctx context.Context, slug string, credentials map[string]string) (store.Deployment, error)
Deploy deploys slug from the image its deployment already uses: the catalog's, or the one the user chose on an earlier deploy. It is DeployImage with the image left out, which is what every caller that never shows an Image box should mean.
func (*Manager) DeployImage ¶ added in v0.22.0
func (m *Manager) DeployImage(ctx context.Context, slug string, credentials map[string]string, image *string) (store.Deployment, error)
DeployImage deploys slug, running image instead of the catalog's when one is given. nil keeps the image the deployment already records, "" goes back to the catalog, and anything else must pass ValidateImage before the runtime is touched. The choice is recorded with the deployment, so every later redeploy keeps it until cleared.
Only the image changes. Capabilities, devices, ports, the entrypoint and the stop timeout still come from the catalog entry, so a different image gains nothing the service does not already have.
func (*Manager) DeployProxied ¶ added in v0.38.0
DeployProxied runs a copy of slug through proxy id. The service must already be deployed here: the copy runs with its image and credentials, under its own device names.
func (*Manager) DeployWith ¶ added in v0.23.0
func (m *Manager) DeployWith(ctx context.Context, slug string, credentials map[string]string, opts DeployOptions) (store.Deployment, error)
DeployWith deploys slug with the given options. The first copy is deployed exactly as a single-copy service always was; copies 2..N follow it, and copies above N that are still running are removed, highest first.
func (*Manager) ExecRunning ¶ added in v0.29.0
func (m *Manager) ExecRunning(ctx context.Context, slug string, cmd []string, timeout time.Duration) ([]noderead.Output, error)
ExecRunning runs a catalog command in every running container of slug, through a runtime that has containers to run it in (Docker); any other runtime answers with an error, so nothing is read. It is noderead.Runner for the collectors.
func (*Manager) HasNativeRuntime ¶ added in v0.10.0
HasNativeRuntime reports whether a provider is registered under the native runtime kind. Native execution has no external dependency (no daemon or socket to reach), so a registered native provider is by construction available — the app surfaces this alongside Docker's Status so onboarding can proceed on either signal. It reflects registration only; it never probes a running process.
func (*Manager) LastRunLogs ¶ added in v0.28.1
LastRunLogs returns the log of the service's last finished run only (see runtime.DockerProvider.LastRunLogs); any other runtime answers with an error, so no refusal is judged from a log that may mix runs.
func (*Manager) List ¶ added in v0.10.0
List returns every managed unit across all registered providers as a single flat slice — the monitoring/health view used by the app's health sampler. An error is returned only when no provider listed successfully; a partial failure yields the healthy providers' units (the failing provider's error is non-fatal). With just Docker registered this returns Docker's list unchanged, or Docker's error.
func (*Manager) ListCustom ¶ added in v0.33.0
func (m *Manager) ListCustom() ([]CustomServiceView, error)
ListCustom returns every custom service as the editor may see it.
func (*Manager) ListProxies ¶ added in v0.38.0
ListProxies returns every proxy without its secrets, with its copies as the last status read saw them.
func (*Manager) LoadCustom ¶ added in v0.33.0
LoadCustom puts the stored custom services into the catalog overlay, masked, so every lookup by slug (names, the dashboard, stop, remove) finds them.
func (*Manager) LogsMatching ¶ added in v0.25.3
func (m *Manager) LogsMatching(ctx context.Context, slug string, since time.Duration, match *regexp.Regexp, lines int) (string, error)
LogsMatching returns the matching log lines of the last `since`, from a runtime that can read a window; any other runtime answers with an error, so nothing is judged.
func (*Manager) PlanRemoval ¶ added in v0.17.8
PlanRemoval reports what removing a service would delete, so the confirmation the user is shown can name the data instead of saying "and its volumes".
func (*Manager) ProxiedCopies ¶ added in v0.38.0
func (m *Manager) ProxiedCopies() []runtime.ProxiedCopy
ProxiedCopies is the latest status read of the proxied copies on this machine.
func (*Manager) ProxyRefusal ¶ added in v0.38.0
ProxyRefusal is why slug cannot run through a proxy here, or "".
func (*Manager) ProxyTick ¶ added in v0.38.0
ProxyTick is the once-a-minute pass: read the proxied copies (which also starts an earner whose tunnel came back), add each tunnel's traffic to its proxy, stop the copies of a proxy at its cap, and start a new period where the reset day came. It returns the proxies that crossed their cap in this pass.
While a cap holds, every pass that still sees a copy of that proxy running stops it again, so a copy started behind the app's back cannot keep spending the allowance.
func (*Manager) ReadState ¶ added in v0.31.0
ReadState reads slug's critical volumes, and only those, refusing more than statebackup.MaxStateBytes.
func (*Manager) Register ¶ added in v0.10.0
Register adds a provider under the given runtime kind. It is the registration point the app uses to plug in additional runtimes (e.g. the native process runtime) after construction. Call it during Startup before the manager is shared with background reconciliation goroutines; it is not synchronized against a running Refresh.
func (*Manager) Remove ¶
Remove removes the service. deleteData decides whether the data it stored goes with it; allowCritical is the separate yes needed for the volumes whose loss cannot be undone. Both default to false, so the ordinary "remove this service" leaves every node identity and keystore on disk for a later redeploy to pick up.
func (*Manager) RemoveProxied ¶ added in v0.38.0
RemoveProxied removes a proxied copy and its record.
func (*Manager) RequiredCredentialsMet ¶ added in v0.11.0
RequiredCredentialsMet reports whether every required field for the service is present in the given credentials. Unlike ValidateCredentials it does not reject a manually tracked service, so the settings "Configured" badge can reflect whether the stored blob actually satisfies the current schema — not merely that it is non-empty, which an orphaned pre-migration blob (wrong keys) would also be.
func (*Manager) ResetProxy ¶ added in v0.38.0
ResetProxy starts a new traffic period by hand and starts the copies the cap stopped. It returns the copies it started.
func (*Manager) SaveCustom ¶ added in v0.33.0
func (m *Manager) SaveCustom(slug string, in CustomDefinition) (CustomServiceView, error)
SaveCustom creates a custom service (slug "") or replaces one's definition. A running service keeps what it was deployed with until it is redeployed.
func (*Manager) SaveProxy ¶ added in v0.38.0
func (m *Manager) SaveProxy(ctx context.Context, id int64, values map[string]string) (proxies.View, error)
SaveProxy creates a proxy (id 0) or edits one. On an edit a blank secret keeps the stored one. A cap turned on starts a fresh period; one turned off or raised above this period's use lifts the stop and starts the copies it stopped.
func (*Manager) ScalingLimit ¶ added in v0.23.0
func (m *Manager) ScalingLimit(svc catalog.Service) ScalingLimit
ScalingLimit decides the Instances box for svc. One copy where the provider allows one device per IP (a second copy behind the same address earns nothing), where the service has host volumes or published ports (copies would share the directories and fight over the ports), where a typed device id (DeviceLink) names the device, since every copy would carry the same one, and where it runs as a native program here, which this app starts once. Otherwise MaxInstances. The reasons are the web app's wording.
func (*Manager) ScalingLimits ¶ added in v0.23.0
func (m *Manager) ScalingLimits(services []catalog.Service) map[string]ScalingLimit
ScalingLimits is ScalingLimit for every service in the catalog, by slug, for the deploy form.
func (*Manager) SignalVars ¶ added in v0.25.3
SignalVars is what a health signal's ${VAR} placeholders are filled from: the catalog defaults, overlaid by the values saved for this service.
func (*Manager) StartProxied ¶ added in v0.38.0
StartProxied starts a proxied copy, refused while its proxy is capped.
func (*Manager) StateFingerprint ¶ added in v0.31.0
StateFingerprint is where slug's irreplaceable state lives right now, as a short hash (see statebackup.Fingerprint). "" with an error when it cannot be read.
func (*Manager) StopProxied ¶ added in v0.38.0
StopProxied stops a proxied copy. A stop by hand is the owner's decision, so a later cap reset does not start it again.
func (*Manager) TestProxy ¶ added in v0.38.0
TestProxy brings up a throwaway tunnel and reports the exit IP and country it gets. The outcome stays on the proxy, so a failure outlives the toast that showed it.
func (*Manager) ValidateCredentials ¶ added in v0.11.0
ValidateCredentials reports whether the given credentials would let the service deploy — mirroring Deploy's pre-checks (known, deployable, required fields present) — so a caller can validate BEFORE persisting anything.
func (*Manager) ValidateDeploy ¶ added in v1.0.7
ValidateDeploy is ValidateCredentials for a deploy: a value that cannot be published also says that nothing was deployed and the running service was not touched, which a caller that only saves the credentials must not claim.
type ProxiedResult ¶ added in v0.38.0
type ProxiedResult struct {
ExitIP string `json:"exitIp"`
Country string `json:"country"`
Warning string `json:"warning"`
}
ProxiedResult is what deploying a proxied copy reports.
type ProxyTestResult ¶ added in v0.38.0
type ProxyTestResult struct {
ExitIP string `json:"exitIp"`
Country string `json:"country"`
MS int64 `json:"ms"`
}
ProxyTestResult is what Test reports.
type ScalingLimit ¶ added in v0.23.0
ScalingLimit is how many copies of a service this machine may run, and why not more. Reason is "" when more than one is allowed.