destination

package
v0.6.1012 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package destination is where the person keeps the places a run's deliverables may be sent. A destination is saved by name: its kind and its non-secret fields in destinations.yaml under the CLI's configuration folder, and its credentials (the secret that signs a webhook's body, and the value of an Authorization header when the receiver wants one; a bucket's access key id and secret access key) in the system keychain, under accounts of the same service the CLI's other saved keys use, so the CLI and the desktop read and write the same entries.

A destination is the person's alone: no manifest field, QuickAgent or schedule names one. A run delivers to the destinations it is given by name (--destination, a QuickAgent's default set the person chose, or a schedule that kept the names) and nowhere else.

Index

Constants

View Source
const (
	KindWebhook = send.KindWebhook
	KindS3      = send.KindS3
)

The kinds a destination can be: a webhook that receives one signed POST, and a bucket of an S3 API that receives each file as an object.

View Source
const (
	MaxDestinations = 64
	MaxPerRun       = 8
)

MaxDestinations bounds how many a person keeps, and MaxPerRun how many one run delivers to.

View Source
const File = "destinations.yaml"

File is the folder's destinations.yaml name.

View Source
const MaxFileBytes = 64 << 10

MaxFileBytes bounds a destinations file.

Variables

This section is empty.

Functions

func AccessKeyAccount

func AccessKeyAccount(name string) string

func AccessKeyID

func AccessKeyID(name string) (string, error)

AccessKeyID is a bucket destination's saved access key id.

func AuthorizationAccount

func AuthorizationAccount(name string) string

func DeleteSecrets

func DeleteSecrets(name string) error

DeleteSecrets removes a destination's credentials from the keychain.

func HasAccessKey

func HasAccessKey(name string) bool

HasAccessKey says whether an access key id is saved for the destination.

func HasAuthorization

func HasAuthorization(name string) bool

HasAuthorization says whether an Authorization value is saved for it.

func HasSecret

func HasSecret(name string) bool

HasSecret says whether a signing secret is saved for the destination.

func Path

func Path() (string, error)

Path is the destinations file.

func Restore

func Restore(name string, sv Saved)

Restore puts the credentials of a snapshot back, removing any the snapshot did not hold. Best effort: it is for the path of a failed save.

func SaveS3Credentials

func SaveS3Credentials(name, accessKeyID, secret string) error

SaveS3Credentials keeps a bucket destination's access key id and secret access key in the system keychain; an empty one leaves the saved value as it is.

func SaveSecrets

func SaveSecrets(name, secret, authorization string) error

SaveSecrets keeps a destination's credentials in the system keychain. An empty authorization removes any saved one, and an empty secret leaves the saved secret as it is.

func SecretAccount

func SecretAccount(name string) string

SecretAccount, AuthorizationAccount and AccessKeyAccount are the keychain accounts of a destination's secret (a webhook's signing secret, a bucket's secret access key), its Authorization value and a bucket's access key id.

func Secrets

func Secrets(name string) (secret, authorization string, err error)

Secrets are a destination's credentials as saved: the signing secret, and the Authorization value when there is one.

func ValidName

func ValidName(name string) bool

ValidName says whether name can name a destination: one to forty lower-case letters, digits, dots, hyphens and underscores, beginning with a letter or digit.

func ValidS3Credentials

func ValidS3Credentials(accessKeyID, secret string) bool

ValidS3Credentials says whether an access key id and a secret access key (an empty one: not given) are values the delivery step can sign with.

func ValidSecretValues

func ValidSecretValues(secret, authorization string) bool

ValidSecretValues says whether a signing secret (empty: none given) and an Authorization value (empty: none) are values the delivery step can use.

Types

type Destination

type Destination struct {
	Name string `yaml:"name" json:"name"`
	Kind string `yaml:"kind" json:"kind"`
	// URL is the webhook's address.
	URL string `yaml:"url,omitempty" json:"url,omitempty"`
	// Bucket, Prefix, Region and Endpoint are a bucket's fields: where its
	// objects go (bucket/prefix/run id/file), the signing region, and the
	// service's address when it is not Amazon's (R2, MinIO).
	Bucket   string `yaml:"bucket,omitempty" json:"bucket,omitempty"`
	Prefix   string `yaml:"prefix,omitempty" json:"prefix,omitempty"`
	Region   string `yaml:"region,omitempty" json:"region,omitempty"`
	Endpoint string `yaml:"endpoint,omitempty" json:"endpoint,omitempty"`
	// OnMyNetwork lets the delivery reach an address on the person's own
	// network (private, shared or loopback space), and http as well as
	// https on any port. Without it a delivery reaches public addresses on
	// port 443 alone.
	OnMyNetwork bool `yaml:"onMyNetwork,omitempty" json:"onMyNetwork,omitempty"`
}

Destination is one saved destination's non-secret fields.

func (Destination) Check

func (d Destination) Check() error

Check holds a destination to its rules: a name, a kind this CLI sends to, and an address the delivery step's own rule accepts. A webhook names an address and no bucket field; a bucket names its bucket and region, and no address but an optional endpoint.

func (Destination) S3Spec

func (d Destination) S3Spec() send.S3Spec

S3Spec is a bucket destination's fields as the delivery step reads them.

func (Destination) SameReceiver

func (d Destination) SameReceiver(o Destination) bool

SameReceiver says two destinations reach the same receiver in the same way, so that a credential saved for the first may be kept for the second. A webhook is the same receiver when the scheme, host and port are the same and so is the *On my network* rule (a change of path or query is not a change of receiver); a bucket when both are Amazon's (an access key reaches every bucket and region of its account) or both name the same endpoint by the same scheme, port and rule. Different kinds, or an address that does not pass its rule, are never the same. Every client that keeps a saved credential across a change asks this one question.

func (Destination) Where

func (d Destination) Where() string

Where describes a destination without its path or query, which may carry a receiver's own token: the scheme, host and port the delivery reaches. A bucket is s3://bucket/prefix and the service's host and port.

type Resolved

type Resolved struct {
	Destination
	// Secret signs the webhook's body, or is a bucket's secret access key;
	// Authorization is the value of the Authorization header, empty when the
	// receiver wants none; AccessKeyID is a bucket's access key id.
	Secret        string `json:"-" yaml:"-"`
	Authorization string `json:"-" yaml:"-"`
	AccessKeyID   string `json:"-" yaml:"-"`
	// Hosted says a driver such as a sandbox host handed the destination in
	// a destinations file (FromFile), the one way a hosted run has any.
	Hosted bool `json:"-" yaml:"-"`
}

Resolved is a destination with its credentials read, as the engine takes it. Its secrets are the engine's alone: they reach the delivery step on its stdin.

func FromFile

func FromFile(path string, getenv func(string) string) (dests []Resolved, envNames []string, err error)

FromFile reads the destinations a driver such as a sandbox host hands a run: a JSON document of non-secret fields (name, kind, and a webhook's url or a bucket's bucket, prefix, region and endpoint) with, for each, the name of the environment variable holding its signing secret (a bucket's secret access key) and, when the receiver wants one, the one holding a webhook's Authorization value (a bucket's access key id). It answers the destinations with their credentials read through getenv, and the names of the variables it read, which the caller removes from its own environment so that no process it starts inherits them.

Every address must pass the rule of a destination that is not on the person's network, so a delivery reaches public addresses on port 443 alone. A missing, empty or malformed value, a name that is not a valid destination name, a kind this CLI does not send to, an unknown field or the same name twice refuses the file as a whole; a delivery is never unsigned and never silently goes nowhere. No error carries a credential's value.

func Resolve

func Resolve(names []string) ([]Resolved, error)

Resolve reads the destinations a run was given by name, with their credentials, in the order named and each once. A name that is not saved, or a destination with no signing secret (a bucket: no key pair), refuses the run before it starts: a delivery never silently goes unsigned or nowhere.

type Saved

type Saved struct {
	Secret, Authorization, AccessKeyID string
}

Saved is a destination's credentials as they were saved, to put back when a change that wrote some of them cannot be finished.

func Snapshot

func Snapshot(name string) Saved

Snapshot reads the destination's saved credentials.

type Store

type Store struct {
	Destinations []Destination `yaml:"destinations,omitempty"`
	// Defaults is each QuickAgent's default set: the names a run of it
	// delivers to when the run names none. The key is namespace/name, so a
	// new version keeps it.
	Defaults map[string][]string `yaml:"defaults,omitempty"`
}

Store is the destinations file as a program reads and writes it.

func Load

func Load() (Store, error)

Load reads the destinations file; a missing one is an empty store.

func (Store) DefaultsFor

func (s Store) DefaultsFor(ref string) []string

DefaultsFor are the names a run of the QuickAgent (a release ref, namespace/name@version, or namespace/name) delivers to when it names none.

func (*Store) Delete

func (s *Store) Delete(name string) bool

Delete removes the destination and every default set's mention of it.

func (Store) Find

func (s Store) Find(name string) (Destination, bool)

Find is the destination saved under name.

func (Store) Save

func (s Store) Save() error

Save writes the store, atomically and for the person alone.

func (Store) SealAccounts

func (s Store) SealAccounts(name string) (required, optional []string)

SealAccounts are the keychain accounts a destination's deliveries read, each with whether it must be there: what a signed-out schedule seals so that a fire sends from it alone. A name that is not saved has the webhook's.

func (*Store) SetDefault

func (s *Store) SetDefault(agent string, names []string) error

SetDefault sets the QuickAgent's default set to names, each saved and none twice; no names clears it.

func (*Store) Upsert

func (s *Store) Upsert(d Destination) error

Upsert adds d or replaces the destination of its name, in name order.

Jump to

Keyboard shortcuts

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