services

package
v1.0.3 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: GPL-3.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source
const (

	// CustomDefaultMemLimit is the memory limit a custom service gets when none is given.
	CustomDefaultMemLimit = "512m"
)
View Source
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.

View Source
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

func CustomImageWarnings(image string) []string

CustomImageWarnings is what is worth telling the user about an image reference.

func CustomVolumeName added in v0.33.0

func CustomVolumeName(slug string) string

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

func MakeCustomSlug(name string, taken map[string]bool) string

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

func ValidateImage(image string) error

ValidateImage refuses a typed image that is not an image reference. "" is valid: it means the catalog image.

Types

type CapNotice added in v0.38.0

type CapNotice struct {
	ProxyID int64
	Name    string
	Message string
}

CapNotice is a proxy whose cap holds, for the notification list.

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

func NewManager(provider runtime.Provider, cat *catalog.Catalog, st *store.Store) *Manager

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

func (m *Manager) CapNotices() []CapNotice

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

func (m *Manager) ContainerDrift(ctx context.Context) map[string][]string

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

func (m *Manager) DeleteCustom(ctx context.Context, slug string) error

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

func (m *Manager) DeleteProxy(id int64) error

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

func (m *Manager) DeployProxied(ctx context.Context, slug string, id int64) (ProxiedResult, error)

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

func (m *Manager) HasNativeRuntime() bool

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

func (m *Manager) LastRunLogs(ctx context.Context, slug string, lines int) (string, error)

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

func (m *Manager) List(ctx context.Context) ([]runtime.ContainerInfo, error)

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

func (m *Manager) ListProxies() ([]proxies.View, error)

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

func (m *Manager) LoadCustom() error

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) Logs

func (m *Manager) Logs(ctx context.Context, slug string, lines int) (string, error)

func (*Manager) LogsCopy added in v0.23.0

func (m *Manager) LogsCopy(ctx context.Context, slug string, n, lines int) (string, error)

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

func (m *Manager) PlanRemoval(ctx context.Context, slug string) (runtime.RemovalPlan, error)

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

func (m *Manager) ProxyRefusal(slug string) string

ProxyRefusal is why slug cannot run through a proxy here, or "".

func (*Manager) ProxyTick added in v0.38.0

func (m *Manager) ProxyTick(ctx context.Context) ([]CapNotice, error)

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

func (m *Manager) ReadState(ctx context.Context, slug string) ([]byte, []string, error)

ReadState reads slug's critical volumes, and only those, refusing more than statebackup.MaxStateBytes.

func (*Manager) Refresh

func (m *Manager) Refresh(ctx context.Context) ([]store.Deployment, error)

func (*Manager) Register added in v0.10.0

func (m *Manager) Register(kind string, provider runtime.Provider)

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

func (m *Manager) Remove(ctx context.Context, slug string, deleteData, allowCritical bool) error

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

func (m *Manager) RemoveProxied(ctx context.Context, slug string, id int64) error

RemoveProxied removes a proxied copy and its record.

func (*Manager) RequiredCredentialsMet added in v0.11.0

func (m *Manager) RequiredCredentialsMet(slug string, credentials map[string]string) bool

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

func (m *Manager) ResetProxy(ctx context.Context, id int64) ([]string, error)

ResetProxy starts a new traffic period by hand and starts the copies the cap stopped. It returns the copies it started.

func (*Manager) Restart

func (m *Manager) Restart(ctx context.Context, slug string) error

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

func (m *Manager) SignalVars(slug string) map[string]string

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) Start added in v0.6.0

func (m *Manager) Start(ctx context.Context, slug string) error

func (*Manager) StartCopy added in v0.23.0

func (m *Manager) StartCopy(ctx context.Context, slug string, n int) error

func (*Manager) StartProxied added in v0.38.0

func (m *Manager) StartProxied(ctx context.Context, slug string, id int64) error

StartProxied starts a proxied copy, refused while its proxy is capped.

func (*Manager) StateFingerprint added in v0.31.0

func (m *Manager) StateFingerprint(ctx context.Context, slug string) (string, error)

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) Stop

func (m *Manager) Stop(ctx context.Context, slug string) error

func (*Manager) StopCopy added in v0.23.0

func (m *Manager) StopCopy(ctx context.Context, slug string, n int) error

func (*Manager) StopProxied added in v0.38.0

func (m *Manager) StopProxied(ctx context.Context, slug string, id int64) error

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

func (m *Manager) TestProxy(ctx context.Context, id int64) (ProxyTestResult, error)

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

func (m *Manager) ValidateCredentials(slug string, credentials map[string]string) error

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.

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

type ScalingLimit struct {
	Max    int    `json:"max"`
	Reason string `json:"reason"`
}

ScalingLimit is how many copies of a service this machine may run, and why not more. Reason is "" when more than one is allowed.

Jump to

Keyboard shortcuts

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