Documentation
¶
Index ¶
- func CodeAttributesURL(code, signupURL string) bool
- func HasDigestPin(image string) bool
- func ImageOutdated(deployed, catalogImage string) bool
- func IsRetired(status string) bool
- type Cashout
- type Catalog
- type CollectorMetadata
- type CriticalVolume
- type Disclosure
- type DockerConfig
- type EarningsEstimate
- type EnvVar
- type HealthSignal
- type NativeBinary
- type NativeConfig
- type Payment
- type Payout
- type Referral
- type ReferralBonus
- type Requirements
- type ResourceLimits
- type Service
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CodeAttributesURL ¶ added in v0.17.7
CodeAttributesURL reports whether a referral code is ANCHORED in a signup URL, which is a different question from whether the string appears in it. The code "grass" is a substring of "https://app.grass.io/register": that is a hostname coincidence, not attribution, and a check that accepts it would report a link as carrying a code that the provider will never read.
A code counts only where a provider actually reads one, which is the placement the catalog schema documents: a query-parameter value (?ref=CODE), a bare query key (?CODE, spide's shape), or a whole path segment (/i/CODE, as earnapp, honeygain and uprock use). Anything else is a URL that has quietly lost its attribution.
This is the Go half of scripts/referral_check.py in the web repository; the two have to agree, because a domain migration that drops the code is caught by whichever of them runs first.
func HasDigestPin ¶ added in v0.17.7
HasDigestPin reports whether an image reference pins an immutable digest.
It is deliberately stricter than "contains @sha256:". A reference like "repo@sha256:aaaa" contains that substring, is not a digest anything can resolve, and would satisfy a substring check while pinning nothing at all — the pin rule would report a service as pinned that is still floating. A sha256 digest is exactly 64 lowercase hex characters, and the registry API rejects anything else, so a reference that fails this check would fail at pull time too.
Lowercase is required rather than folded: the OCI digest grammar defines the hex as lowercase, and an uppercase digest is a typed-by-hand pin that will not match the registry's own.
One rule, one place: the catalog's pin gate and the catalog-overlay pin checks both call this, so tightening it cannot tighten only one of them.
func ImageOutdated ¶ added in v0.11.0
ImageOutdated reports whether a running container's image no longer matches the catalog entry it was deployed from. It is true when the provider changed the image path (the ProxyBase migration) or the catalog re-pinned to a new digest, so the UI can prompt a re-deploy instead of showing a healthy-looking container that is silently running a retired image and earning nothing. Deliberately conservative: unknown/empty images and a pure tag-vs-digest difference of the same repository are NOT flagged.
Types ¶
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
func (*Catalog) ListVisible ¶
type CollectorMetadata ¶
type CollectorMetadata struct {
Type string `json:"type" yaml:"type"`
// Notes are implementation hints for whoever writes the collector.
Notes string `json:"notes" yaml:"notes"`
// CredentialHint is written for the USER, not the developer: the sentence
// someone reads while looking at a provider dashboard they have never seen
// before. It allows limited HTML (<a>, <b>) because the UI inserts it as markup
// deliberately.
CredentialHint string `json:"credentialHint" yaml:"credential_hint"`
// PerNodeEarnings says the collector can break earnings down per node rather
// than reporting only an account total.
PerNodeEarnings bool `json:"perNodeEarnings" yaml:"per_node_earnings"`
}
type CriticalVolume ¶ added in v0.17.7
type CriticalVolume struct {
Target string `json:"target" yaml:"target"`
Holds string `json:"holds" yaml:"holds"`
}
CriticalVolume is one mount holding state that cannot be recovered if it is destroyed. Target must match the container-side path in Volumes; Holds is what is lost, written to be shown to the operator being asked to confirm.
type Disclosure ¶ added in v0.17.7
type Disclosure struct {
Sells string `json:"sells" yaml:"sells"`
// ThirdPartyTraffic opens with a standalone yes/no/unknown followed by
// punctuation so it can be read programmatically as well as by a person.
ThirdPartyTraffic string `json:"thirdPartyTraffic" yaml:"third_party_traffic"`
DataCollected string `json:"dataCollected" yaml:"data_collected"`
ISPRisk string `json:"ispRisk" yaml:"isp_risk"`
AccountRules string `json:"accountRules" yaml:"account_rules"`
}
Disclosure is what a service does with the user's machine, in plain words. An absent block means nobody has documented it, which the UI must be able to say rather than render as a reassuring blank.
type DockerConfig ¶
type DockerConfig struct {
Image string `json:"image" yaml:"image"`
// Tag is a legacy field a single catalog entry still carries alongside Image. It
// is parsed so the field round-trips, and deliberately not used: Image already
// carries the reference Desktop deploys, digest and all.
Tag string `json:"tag" yaml:"tag"`
// ImageByArch overrides Image per architecture family (keys: amd64, arm64, arm).
// It exists for images whose ARM builds Docker cannot select itself because every
// tag is labelled linux/amd64 in the registry, so the right build is chosen by
// tag rather than by manifest. Falls back to Image when the host's family is
// absent.
ImageByArch map[string]string `json:"imageByArch" yaml:"image_by_arch"`
// Platforms is what the registry PUBLISHES for this image, nothing more. An ARM
// host deploying an entry that lacks its family gets a container that dies with
// "exec format error", so this list is a real check and not a badge.
Platforms []string `json:"platforms" yaml:"platforms"`
Env []EnvVar `json:"env" yaml:"env"`
Ports []string `json:"ports" yaml:"ports"`
Volumes []string `json:"volumes" yaml:"volumes"`
// CriticalVolumes marks the mounts whose loss is unrecoverable — node
// identities, keystores, generated wallets — so deleting one has to be an
// explicit act rather than a side effect of tidying up.
CriticalVolumes []CriticalVolume `json:"criticalVolumes" yaml:"critical_volumes"`
Command string `json:"command" yaml:"command"`
// Entrypoint replaces the image's ENTRYPOINT when set. Storj uses it to give its
// node a real stop grace: the image's supervisord otherwise kills the node 10
// seconds after any stop, however long Docker is willing to wait.
Entrypoint []string `json:"entrypoint" yaml:"entrypoint"`
NetworkMode string `json:"networkMode" yaml:"network_mode"`
// CapAdd are the Linux capabilities the container needs on top of a cap_drop ALL
// baseline. Getting this wrong does not crash the container: Mysterium without
// SETUID and SETGID registers, looks healthy, and fails every session at setup.
CapAdd []string `json:"capAdd" yaml:"cap_add"`
// Devices are host devices to map in ("/dev/net/tun"). A device is a direct line
// to the kernel, so only devices the runtime allow-lists may be requested, and
// only by the service whose own entry declares them.
Devices []string `json:"devices" yaml:"devices"`
// HealthSignals are log patterns that say whether the service is EARNING, which
// container health cannot see. For services with no collector it is the only
// signal there is.
HealthSignals []HealthSignal `json:"healthSignals" yaml:"health_signals"`
// AdvertisedAddressEnv names the ONE env var holding the address the network
// dials this service back at, so it can be compared against the machine's
// current egress address. Only that variable is ever copied out; the rest may
// hold credentials.
AdvertisedAddressEnv string `json:"advertisedAddressEnv" yaml:"advertised_address_env"`
Privileged bool `json:"privileged" yaml:"privileged"`
StopTimeout int `json:"stopTimeout" yaml:"stop_timeout"`
Resources ResourceLimits `json:"resources" yaml:"resources"`
Setup string `json:"setup" yaml:"setup"`
Notes string `json:"notes" yaml:"notes"`
}
type EarningsEstimate ¶
type EnvVar ¶
type EnvVar struct {
Key string `json:"key" yaml:"key"`
Label string `json:"label" yaml:"label"`
Required bool `json:"required" yaml:"required"`
Secret bool `json:"secret" yaml:"secret"`
Description string `json:"description" yaml:"description"`
Default string `json:"default" yaml:"default"`
// Pattern, when set, is a regular expression the WHOLE value must match. It
// exists for values that land on a command line, where "127.0.0.1, 10.0.0.1"
// becomes a stray argument and the service refuses to start.
Pattern string `json:"pattern,omitempty" yaml:"pattern"`
}
type HealthSignal ¶ added in v0.17.7
type HealthSignal struct {
Pattern string `json:"pattern" yaml:"pattern"`
Means string `json:"means" yaml:"means"`
State string `json:"state" yaml:"state"`
}
HealthSignal is one log pattern that reveals whether a service is earning. Pattern is a regex matched case-insensitively against container logs, Means is the explanation shown to the user, and State is "failing" (the default) or "idle".
type NativeBinary ¶ added in v0.10.0
type NativeBinary struct {
OS string `json:"os" yaml:"os"`
Arch string `json:"arch" yaml:"arch"`
URL string `json:"url" yaml:"url"`
SHA256 string `json:"sha256" yaml:"sha256"`
Archive string `json:"archive" yaml:"archive"`
Bin string `json:"bin" yaml:"bin"`
}
NativeBinary is one downloadable, SHA-256-pinned native executable for a specific OS/arch. OS matches Go's runtime.GOOS (darwin|linux|windows) and Arch matches runtime.GOARCH (amd64|arm64). URL must be HTTPS and SHA256 is the hex digest of the downloaded artifact (the archive or the raw binary) — the NativeProcessProvider verifies it and refuses to execute anything that fails or lacks verification. Archive is how the artifact is packaged: "tar.gz", "zip", or "none" (a raw binary). Bin is the path to the executable inside the extracted archive (e.g. "myst" or "myst.exe"); for archive "none" it is the on-disk name to give the raw binary.
type NativeConfig ¶ added in v0.10.0
type NativeConfig struct {
Binaries []NativeBinary `json:"binaries" yaml:"binaries"`
Command string `json:"command" yaml:"command"`
Env []EnvVar `json:"env" yaml:"env"`
}
NativeConfig is the optional native: block from a service YAML. It declares how a service can be run as a supervised native child process (no container): a per OS/arch pinned binary download plus a launch-argument template. It is additive and parallel to DockerConfig — a service may declare docker:, native:, or both. The NativeProcessProvider (internal/runtime) downloads+verifies+extracts the matching Binary and launches it with argv built from Command via the same shell-safe tokenizeCommand/substitute path Docker uses, reusing the existing EnvVar type for Env so the schema stays consistent.
type Payment ¶
type Payment struct {
Methods []string `json:"methods" yaml:"methods"`
// CryptoToken is the specific token when it differs from Currency ("SOL",
// "USDT").
CryptoToken string `json:"cryptoToken" yaml:"crypto_token"`
MinimumPayout string `json:"minimumPayout" yaml:"minimum_payout"`
Currency string `json:"currency" yaml:"currency"`
Frequency string `json:"frequency" yaml:"frequency"`
}
type Payout ¶ added in v0.17.7
type Payout struct {
// Model is one of external, internal, minted, unknown. "unknown" is a deliberate
// value, not a placeholder.
Model string `json:"model" yaml:"model"`
// Chain is the settlement chain, or "none" when no on-chain surface exists at
// all. Absent means the chain is chosen per withdrawal and there is no
// persistent on-chain identity.
Chain string `json:"chain" yaml:"chain"`
// AddressEnv is the container env var carrying the user's payout address, for
// external models where the address can be read back from the deployed spec.
AddressEnv string `json:"addressEnv" yaml:"address_env"`
// AddressSource is env, manual (set after deploy, e.g. Mysterium's beneficiary
// via TequilAPI) or app (linked inside the provider's own site).
AddressSource string `json:"addressSource" yaml:"address_source"`
Notes string `json:"notes" yaml:"notes"`
}
Payout is where the money actually lives, which is a different question from Cashout's "how do I withdraw it". Model is the load-bearing field: "internal" means there is no address to show and no chain to watch, which is not the same as an address nobody has filled in yet.
type Referral ¶
type Referral struct {
SignupURL string `json:"signupUrl" yaml:"signup_url"`
// Code is the referral code itself, kept alongside the URL so a domain migration
// that drops the code from signup_url is detectable rather than silent. Referral
// attribution is revenue: losing it loses money, and it fails invisibly.
Code string `json:"code" yaml:"code"`
// Program is three-valued on purpose and absent is NOT false: true means the
// provider was verified to run a referral programme (true with no Code is an
// actionable gap), false means it was verified not to, nil means nobody has
// checked. Collapsing nil into false would turn "unknown" into "nothing to do".
Program *bool `json:"program" yaml:"program"`
Bonus ReferralBonus `json:"bonus" yaml:"bonus"`
}
type ReferralBonus ¶ added in v0.17.7
type ReferralBonus struct {
Referrer string `json:"referrer" yaml:"referrer"`
Referee string `json:"referee" yaml:"referee"`
}
ReferralBonus is what each side gets for a referral, shown on the service detail page.
type Requirements ¶
type Requirements struct {
ResidentialIP bool `json:"residentialIp" yaml:"residential_ip"`
VPSIP bool `json:"vpsIp" yaml:"vps_ip"`
DevicesPerAccount int `json:"devicesPerAccount" yaml:"devices_per_account"`
// DevicesPerIP is a pointer because omitted and 0 mean different things and the
// difference is what the user is told. Omitted means nobody has documented a
// per-IP limit, so a second instance behind one address needs checking against
// the provider's terms. 0 is a verified statement that there is no limit, which
// downgrades that warning to "the pair shares one connection, so it earns about
// what one does". Reading an omitted value as 0 turns a cautious message into a
// wrong one.
DevicesPerIP *int `json:"devicesPerIp" yaml:"devices_per_ip"`
MinBandwidth string `json:"minBandwidth" yaml:"min_bandwidth"`
GPU bool `json:"gpu" yaml:"gpu"`
MinStorage string `json:"minStorage" yaml:"min_storage"`
// ContainerProhibited is set only when the provider explicitly forbids running
// its software in containers, VMs or on servers. It is the strongest verdict in
// the catalog: the stated penalty is a terminated account with the pending
// balance cancelled, and deploying it as a container IS the violation.
ContainerProhibited bool `json:"containerProhibited" yaml:"container_prohibited"`
Note string `json:"note" yaml:"note"`
// NoteColumn says which column Note is a footnote for (vps_ip, devices_per_ip).
NoteColumn string `json:"noteColumn" yaml:"note_column"`
}
type ResourceLimits ¶ added in v0.8.0
type ResourceLimits struct {
MemLimit string `json:"memLimit" yaml:"mem_limit"`
MemReservation string `json:"memReservation" yaml:"mem_reservation"`
OomScoreAdj *int `json:"oomScoreAdj" yaml:"oom_score_adj"`
// arbitrates between containers while the host is contended — it never caps
// an idle container. A plain int64 is right here, unlike OomScoreAdj's
// pointer: Docker already reads 0 as "use the default", so the zero value IS
// absent and needs no separate representation.
CPUShares int64 `json:"cpuShares" yaml:"cpu_shares"`
}
ResourceLimits is the optional docker.resources block from a service YAML. Its fields map to Docker HostConfig knobs applied at container creation (see internal/runtime.applyResourceLimits) so a service's memory ceiling and OOM priority survive restarts instead of being set out-of-band. MemLimit and MemReservation are Docker-style size strings ("768m", "2g"); an empty string leaves that limit unset. OomScoreAdj is a pointer so an absent value is distinguishable from an explicit 0 and is applied only when present.
type Service ¶
type Service struct {
Name string `json:"name" yaml:"name"`
Slug string `json:"slug" yaml:"slug"`
Category string `json:"category" yaml:"category"`
Status string `json:"status" yaml:"status"`
// Priority orders the catalog: entries with one come first, lowest number first,
// before the usual category-then-name order; 0 means none. The web catalog sets it
// on the services that pay the project best, so a reorder is a number change there.
Priority int `json:"priority" yaml:"priority"`
Website string `json:"website" yaml:"website"`
Description string `json:"description" yaml:"description"`
ShortDescription string `json:"shortDescription" yaml:"short_description"`
Referral Referral `json:"referral" yaml:"referral"`
Docker DockerConfig `json:"docker" yaml:"docker"`
Native NativeConfig `json:"native" yaml:"native"`
Requirements Requirements `json:"requirements" yaml:"requirements"`
Payment Payment `json:"payment" yaml:"payment"`
Earnings EarningsEstimate `json:"earnings" yaml:"earnings"`
Cashout Cashout `json:"cashout" yaml:"cashout"`
Platforms []string `json:"platforms" yaml:"platforms"`
Collector CollectorMetadata `json:"collector" yaml:"collector"`
Payout Payout `json:"payout" yaml:"payout"`
Disclosure Disclosure `json:"disclosure" yaml:"disclosure"`
// ResurrectionChecked is the date ("YYYY-MM-DD") on which a human confirmed a
// dead entry's programme really is gone even though its site still answers. It is
// carried so the reason a dead service stays dead travels with the entry instead
// of living only in the web repository's history.
ResurrectionChecked string `json:"resurrectionChecked" yaml:"resurrection_checked"`
SourcePath string `json:"sourcePath" yaml:"-"`
ManualOnly bool `json:"manualOnly" yaml:"-"`
}
func (Service) HasNative ¶ added in v0.10.0
HasNative reports whether the service declares at least one native binary, i.e. it can be run as a supervised native child process (by the NativeProcessProvider) instead of, or in addition to, a Docker container. It is the native counterpart of the "has a Docker image" check that drives ManualOnly and runtime routing.
func (Service) NativeBinaryFor ¶ added in v0.10.0
func (s Service) NativeBinaryFor(goos, goarch string) (NativeBinary, bool)
NativeBinaryFor returns the native binary declared for the given GOOS/GOARCH (as in Go's runtime.GOOS/GOARCH), and whether one exists. It is used both by the runtime provider (to pick the artifact to download) and by routing (to prefer native only when this host actually has a native binary available).