catalog

package
v1.0.11 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const (
	SignalFailing         = "failing"
	SignalIdle            = "idle"
	SignalAccountDisabled = "account_disabled"
)

Health signal states the catalog allows. An absent state means failing.

View Source
const CustomPrefix = "custom-"

CustomPrefix starts every custom service's slug, and no catalog slug may use it: an entry with such a slug would take over a user's service and hand it whatever capabilities, devices or ports the entry declares.

View Source
const MaxUDPPorts = 300

MaxUDPPorts is the most UDP ports one udp_port_range may publish, the web catalog's ceiling. Each published port is a rule and, with Docker's userland proxy, a process on the host, and each one slows the container's start: measured on a live node, 300 ports start in about 12 s and 1,000 in about 51 s. An entry's own max_ports (UDPPortRange.Cap) is what a deploy enforces; this only bounds it.

View Source
const NotRated = "Not rated yet"

NotRated is what a provider without a valid rating block shows.

View Source
const RatingRulesFile = "_ratings.yml"

RatingRulesFile is the published method, beside the service files.

Variables

This section is empty.

Functions

func CodeAttributesURL added in v0.17.7

func CodeAttributesURL(code, signupURL string) bool

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 ExpandUDPRange added in v1.0.5

func ExpandUDPRange(value string, limit int) ([]int, error)

ExpandUDPRange is the ports of "start:end", in order. A blank value publishes nothing. A value that is not a well-ordered range, or one wider than limit, is an error: a node can only use a forwarded range when each port reaches the same port in the container, so nothing short of the whole range is published.

func HasDigestPin added in v0.17.7

func HasDigestPin(image string) bool

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

func ImageOutdated(deployed, catalogImage string) bool

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.

func IsCustomSlug added in v0.33.0

func IsCustomSlug(slug string) bool

IsCustomSlug reports whether slug names a service the user added themselves.

func IsPortRange added in v0.35.0

func IsPortRange(value string) bool

IsPortRange reports whether value is "start:end" in ASCII digits with 1 <= start <= end <= 65535.

func IsRetired added in v0.17.7

func IsRetired(status string) bool

IsRetired reports whether a status hides the service from the UI.

func UIBindings added in v1.0.5

func UIBindings(value string) ([]netip.Addr, error)

UIBindings is each IPv4 address in a comma-separated list, deduplicated, with "localhost" read as 127.0.0.1 (Docker binds addresses, not names). An empty list is 127.0.0.1, the catalog's default. Anything that is not an IPv4 address is an error: published as is, it would fail the container's start.

func ValidSignal added in v0.28.1

func ValidSignal(s HealthSignal) bool

ValidSignal reports whether the web catalog would accept this health signal, with State already lowercased.

Types

type AddressRead added in v0.27.0

type AddressRead struct {
	Command []string `json:"command" yaml:"command"`
	Pattern string   `json:"pattern" yaml:"pattern"`
}

AddressRead is a read-only command run inside the container and the pattern whose first group is the address.

type Cashout

type Cashout struct {
	Method       string  `json:"method" yaml:"method"`
	DashboardURL string  `json:"dashboardUrl" yaml:"dashboard_url"`
	MinAmount    float64 `json:"minAmount" yaml:"min_amount"`
	Currency     string  `json:"currency" yaml:"currency"`
	Notes        string  `json:"notes" yaml:"notes"`
}

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

func Load

func Load() (*Catalog, error)

func LoadEmbedded

func LoadEmbedded(fsys fs.FS) (*Catalog, error)

func (*Catalog) Get

func (c *Catalog) Get(slug string) (Service, bool)

func (*Catalog) List

func (c *Catalog) List() []Service

List is every catalog entry, then the user's custom services.

func (*Catalog) ListVisible

func (c *Catalog) ListVisible() []Service

func (*Catalog) SetCustom added in v0.33.0

func (c *Catalog) SetCustom(services []Service)

SetCustom replaces the user's custom services. Each must carry the custom- prefix and Custom set; anything else is dropped, so a custom definition can never shadow or stand in for a catalog entry.

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"`
	// QuietDays is how many days the balance can stand still while the service
	// works normally (a vetting period, batched settlements). The web app's
	// "gone quiet" heads-up waits at least this long. Desktop has no such
	// heads-up yet; the field is read so the value is there when it does.
	QuietDays int `json:"quietDays" yaml:"quiet_days"`
	// NodeRead says how to read one node's own earnings from inside its running
	// container, for a provider whose account API gives no balance or lifetime
	// (Mysterium: the cloud's earningsTotal is a trailing 30-day sum). Nil means
	// the service does not declare one.
	NodeRead *NodeRead `json:"nodeRead,omitempty" yaml:"node_read"`
}

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 DeviceLink struct {
	IDEnv string `json:"idEnv" yaml:"id_env"`
	URL   string `json:"url" yaml:"url"`
	Steps string `json:"steps" yaml:"steps"`
}

DeviceLink is the step after a deploy that makes a device earn for the user: the env var holding the device id, where to claim it (${VAR} is filled from the deployed env, URL-encoded) and what to do there. The web catalog's loader refuses an IDEnv that is secret, so the id is safe to show.

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"`
	// Runtime is the one container runtime this service works under ("runc"), set on
	// the container whatever the daemon's default is. Mysterium needs it: gVisor has
	// no iptables-nft and no kernel WireGuard, so the node starts there and carries
	// nothing.
	Runtime string `json:"runtime" yaml:"runtime"`
	// UIPort publishes a WebUI port on each address the named env var lists
	// (comma separated), instead of a static ports entry. See UIBindings.
	UIPort *UIPort `json:"uiPort,omitempty" yaml:"ui_port"`
	// UDPPortRange publishes the start:end range the named env var holds, 1:1, at
	// most MaxPorts ports. See ExpandUDPRange.
	UDPPortRange *UDPPortRange `json:"udpPortRange,omitempty" yaml:"udp_port_range"`
	// FenceGated services run only behind the LAN fence (internal/runtime/lanfence.go):
	// a deploy anywhere else is refused, and they have no compose export. Mysterium
	// holds NET_ADMIN in its own network namespace, and the fence is what keeps that
	// namespace off the LAN, this machine and the tailnet.
	FenceGated bool `json:"fenceGated" yaml:"fence_gated"`
	// NodeFirewall says where a node firewalls its own customers off private ranges
	// (the flag in Command carrying the ranges, the nat chain, the blackhole address).
	// The web worker reads it to check the node's isolation; Desktop parses it so the
	// field round-trips and the strict-decode test passes, and does not act on it.
	NodeFirewall NodeFirewall `json:"nodeFirewall" yaml:"node_firewall"`
	// 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"`
	// HealthProbe is the web catalog's docker.health_probe block: a read-only command
	// the web worker runs inside a running node, with regex checks on its answer
	// (Mysterium's monitoring status and recent sessions). Neither schema file
	// describes it yet. Desktop parses it so the field round-trips and the
	// strict-decode test passes, and does not act on it. The loader makes it
	// JSON-safe (see jsonSafe), since the service list crosses the Wails bridge.
	HealthProbe map[string]any `json:"healthProbe,omitempty" yaml:"health_probe"`
	// 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"`
}

func (DockerConfig) CheckPublishedValues added in v1.0.5

func (d DockerConfig) CheckPublishedValues(env map[string]string) error

CheckPublishedValues reports whether env (the values the container would get) publishes cleanly through ui_port and udp_port_range: the deploy validation asks it so a bad address or an oversized range is refused before anything is touched.

func (DockerConfig) PublishesPorts added in v1.0.5

func (d DockerConfig) PublishesPorts() bool

PublishesPorts reports whether the container publishes any port on the host: static ports, a WebUI port or a UDP range. Two copies cannot share one, and a proxied copy cannot publish one.

type EarningsEstimate

type EarningsEstimate struct {
	MonthlyLow  float64 `json:"monthlyLow" yaml:"monthly_low"`
	MonthlyHigh float64 `json:"monthlyHigh" yaml:"monthly_high"`
	Currency    string  `json:"currency" yaml:"currency"`
	Per         string  `json:"per" yaml:"per"`
	Notes       string  `json:"notes" yaml:"notes"`
}

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"`
	// PortRange, when set, means the value is "start:end" with
	// 1 <= start <= end <= 65535. A pattern checks the shape but not the order, and
	// Mysterium refuses to start on a reversed --udp.ports.
	PortRange bool `json:"portRange,omitempty" yaml:"port_range"`
	// PerDevice means the value is the id the provider knows this device by
	// (ProxyRack's UUID). A copy, proxied or on the box, gets its own value derived
	// from it, or is refused when none can be derived.
	PerDevice bool `json:"perDevice,omitempty" yaml:"per_device"`
}

func (EnvVar) AcceptsValue added in v0.35.0

func (v EnvVar) AcceptsValue(value string) bool

AcceptsValue reports whether a value the user supplied for this field has the format the deploy needs: all of the pattern, and a well-ordered range for a port range field. An empty value is always accepted here; whether it may be empty is the Required/Default question, asked separately.

It is the one rule the deploy validation (services.validateRequired) and the import dry run (internal/importers) both apply, so a value the dry run shows as ready is a value the deploy takes.

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"`
	// Unless cancels the signal when it also appears in the same logs: the problem
	// is not there. WindowHours, when set, judges that many hours of logs instead
	// of the tail (see health.windowed); Mysterium writes about 11,000 lines an
	// hour, so the tail is a minute and cannot show that something never happened.
	Unless      string  `json:"unless,omitempty" yaml:"unless"`
	WindowHours float64 `json:"windowHours,omitempty" yaml:"window_hours"`
	// MinMatches is how many lines the pattern must match in the window (default 1).
	MinMatches int `json:"minMatches,omitempty" yaml:"min_matches"`
}

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), "idle" or "account_disabled": the provider refuses to run the client, so restarting cannot help. The loader lowercases State and drops a signal whose state is none of these (see normalizeSignals), as the web catalog rejects it.

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"`
	Args          string   `json:"args,omitempty" yaml:"args"`
	FirewallBlock []string `json:"firewallBlock,omitempty" yaml:"firewall_block"`
}

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.

Args and FirewallBlock exist because the same program can need different handling per OS. Args is tokenized like Command and placed BEFORE it, so a global flag that only one OS needs still precedes the subcommand. FirewallBlock is Windows-only: the provider keeps an outbound Windows Firewall rule that blocks this binary from these networks for as long as the service is deployed, and refuses to start the binary when the rule cannot be put in place.

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 NodeFirewall added in v0.23.7

type NodeFirewall struct {
	Flag      string `json:"flag" yaml:"flag"`
	Chain     string `json:"chain" yaml:"chain"`
	Blackhole string `json:"blackhole" yaml:"blackhole"`
}

NodeFirewall is the optional docker.node_firewall block (see services/_schema.yml).

type NodeRead added in v0.28.1

type NodeRead struct {
	Command     []string `json:"command" yaml:"command"`
	Node        string   `json:"node" yaml:"node"`
	Balance     string   `json:"balance" yaml:"balance"`
	Lifetime    string   `json:"lifetime" yaml:"lifetime"`
	SettledNet  string   `json:"settledNet,omitempty" yaml:"settled_net"`
	SettledFees string   `json:"settledFees,omitempty" yaml:"settled_fees"`
}

NodeRead is collector.node_read (services/_schema.yml): Command runs inside the node's container, read-only, and each regex's group 1 is taken from its output. SettledNet and SettledFees come both or neither; every match of each is summed.

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"`
	// AddressRead says how the web worker reads a manual address back from the
	// running container. Desktop has no payouts page and does not run it; it is
	// declared so the vendored key is read rather than silently dropped.
	AddressRead *AddressRead `json:"addressRead,omitempty" yaml:"address_read"`
	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 ProxyProhibited added in v0.38.0

type ProxyProhibited struct {
	Source string `json:"source" yaml:"source"`
}

ProxyProhibited is requirements.proxy_prohibited: the provider's own terms that forbid running its software through a proxy or VPN.

type Rating added in v0.36.0

type Rating struct {
	// contains filtered or unexported fields
}

Rating is a service's raw `rating:` block. It is kept as a YAML node and checked at load rather than decoded into a struct, so a bad block (a typed grade, a typo) makes the provider "Not rated yet" instead of failing the whole catalog.

func (*Rating) UnmarshalYAML added in v0.36.0

func (r *Rating) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML keeps the block for validateRating.

type RatingCap added in v0.36.0

type RatingCap struct {
	Key      string `json:"key"`
	MaxGrade string `json:"maxGrade"`
	Reason   string `json:"reason"`
}

RatingCap is a ceiling that lowered the grade the score earned.

type RatingItem added in v0.36.0

type RatingItem struct {
	Text      string `json:"text"`
	Criterion string `json:"criterion"`
	Kind      string `json:"kind"`
	Source    string `json:"source"`
	CheckedOn string `json:"checkedOn"`
}

RatingItem is one cited con or pro.

type RatingResult added in v0.36.0

type RatingResult struct {
	Rated        bool              `json:"rated"`
	Grade        string            `json:"grade"`
	BandGrade    string            `json:"bandGrade"`
	Score        int               `json:"score"`
	Max          int               `json:"max"`
	Percent      float64           `json:"percent"`
	Caps         []RatingCap       `json:"caps"`
	UnknownCount int               `json:"unknownCount"`
	ThinEvidence bool              `json:"thinEvidence"`
	ReviewedOn   string            `json:"reviewedOn"`
	Verdicts     []RatingVerdict   `json:"verdicts"`
	Notes        map[string]string `json:"notes"`
	Cons         []RatingItem      `json:"cons"`
	Pros         []RatingItem      `json:"pros"`
	TopCons      []RatingItem      `json:"topCons"`
	Summary      string            `json:"summary"`
}

RatingResult is a provider's grade with everything that explains it, the same fields app/ratings.py for_service returns (camel-cased for the frontend).

func GradeService added in v0.36.0

func GradeService(svc Service, rules *RatingRules) *RatingResult

GradeService is the grade of one catalog service, computed from rules. A service with no rating block, or one that does not validate, is not rated. rules nil (the method could not be read) leaves everyone not rated.

type RatingRules added in v0.36.0

type RatingRules struct {
	Criteria []struct {
		Key   string `yaml:"key"`
		Title string `yaml:"title"`
	} `yaml:"criteria"`
	Points map[string]int `yaml:"points"`
	Bands  []struct {
		Grade      string  `yaml:"grade"`
		MinPercent float64 `yaml:"min_percent"`
	} `yaml:"bands"`
	Caps []struct {
		Key        string `yaml:"key"`
		MaxGrade   string `yaml:"max_grade"`
		Reason     string `yaml:"reason"`
		MinUnknown int    `yaml:"min_unknown"`
	} `yaml:"caps"`
	Kinds map[string]string `yaml:"kinds"`
}

RatingRules is services/_ratings.yml, the part the grade is computed from.

func ParseRatingRules added in v0.36.0

func ParseRatingRules(raw []byte) (*RatingRules, error)

ParseRatingRules reads the published method and refuses one this build cannot apply faithfully: no criteria, no bands, bands out of order, a letter outside B to F, negative points, or an unknown ceiling.

type RatingVerdict added in v0.36.0

type RatingVerdict struct {
	Key     string `json:"key"`
	Title   string `json:"title"`
	Verdict string `json:"verdict"`
}

RatingVerdict is one criterion's verdict, with its title.

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"`
	// ProxyProhibited is set only when the provider's own terms forbid running its
	// software through a proxy or VPN; a proxied copy of the service is then refused
	// (internal/proxies.Refusal). nil means nobody has documented it, never that it
	// is allowed.
	ProxyProhibited *ProxyProhibited `json:"proxyProhibited,omitempty" yaml:"proxy_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"`
	// CPUShares is a relative CPU weight (Docker's API default is 1024) that only
	// 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"`
	// SupportURL is the provider's support page, offered when it has disabled the
	// account (a health signal with state account_disabled). Only https:// links are
	// kept; anything else is cleared at load.
	SupportURL       string            `json:"supportUrl" yaml:"support_url"`
	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"`
	// DeviceLink is set for providers that pay a device only once the user adds its
	// id to their account by hand (EarnApp, ProxyRack). Nil means nothing to link.
	DeviceLink *DeviceLink `json:"deviceLink" yaml:"device_link"`
	// 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"`
	// Rating is the web catalog's evidence for a provider's grade (verdicts, cons,
	// pros). It is checked at load and turned into RatingResult (rating.go); the
	// block itself never reaches the frontend.
	Rating Rating `json:"-" yaml:"rating"`
	// RatingResult is the grade computed from services/_ratings.yml, or "not rated".
	// Nil for a custom service, which nobody has reviewed. Never read from YAML.
	RatingResult *RatingResult `json:"ratingResult" yaml:"-"`
	SourcePath   string        `json:"sourcePath" yaml:"-"`
	ManualOnly   bool          `json:"manualOnly" yaml:"-"`
	// Custom marks a service the user added from an image reference rather than a
	// reviewed catalog entry. Never read from YAML.
	Custom bool `json:"custom" yaml:"-"`
}

func (Service) HasNative added in v0.10.0

func (s Service) HasNative() bool

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

type UDPPortRange added in v1.0.5

type UDPPortRange struct {
	Env      string `json:"env" yaml:"env"`
	MaxPorts int    `json:"maxPorts,omitempty" yaml:"max_ports"`
}

UDPPortRange is docker.udp_port_range: the start:end range the Env var holds is published 1:1, at most MaxPorts ports (0 means MaxUDPPorts).

func (UDPPortRange) Cap added in v1.0.5

func (r UDPPortRange) Cap() int

Cap is the most ports this range may publish: MaxPorts within 1..MaxUDPPorts.

type UIPort added in v1.0.5

type UIPort struct {
	Env  string `json:"env" yaml:"env"`
	Port int    `json:"port" yaml:"port"`
}

UIPort is docker.ui_port: Port is published on each address the Env var lists.

Jump to

Keyboard shortcuts

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