send

package
v0.7.19-dev.2 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package send is the runner image's `deliver` role: the delivery step that hands a finished run's deliverables to a destination the person chose. The webhook kind is one HTTPS POST of a JSON body that carries the run's id, release reference and digest, its result, and each deliverable's path, title, digest and content, signed with an HMAC the receiver can check.

The caller runs this in a container of its own, on a network whose only route is a CONNECT proxy to the destination's host and port, with the files it may send staged read-only (each already shown to match the digest the run's envelope names) and the credential on stdin: never in the environment, an argument, a file or the report. The step follows no redirect, reads at most a small part of the answer and never records it, and reports each file's outcome as one word from a closed list.

Nothing else runs in that container and each folder it is given is its own: the staged folder and the job folder are mounted read-only, the work folder is the report's alone, and this package starts no process. So no process can write any of them, swap a folder of them for a link, or put a link in place of a staged file while a call here uses it, and the folders are held with os.Root, which refuses a link out of the folder where the runtime applies O_NOFOLLOW to a folder, rather than with beneath.Dir, which guards a folder another process can write. A staged name is one plain file name with no folder in it, so there is no folder on a staged name's way to swap.

This package is part of the embedded runner-image build context and so imports nothing outside the standard library and the runner image's own packages.

Index

Constants

View Source
const (
	// ReportSchema is the report's format; ReportFile is where Run writes it,
	// in the work directory, and JobFile where the caller puts the job it reads.
	ReportSchema = "deliver/v1"
	ReportFile   = "delivery.json"
	JobFile      = "job.json"
	// BodySchema names the format of the body a webhook receives.
	BodySchema = "agentry-delivery/v1"
	// KindWebhook is the kind that posts one signed body; KindS3 (s3target.go)
	// puts each file to a bucket.
	KindWebhook = "webhook"
	// DefaultMaxBody is the most a webhook body is: 10 MiB.
	DefaultMaxBody int64 = 10 << 20
)

The names this package and its caller share.

View Source
const (
	HeaderSignature = "X-Agentry-Signature"
	HeaderTimestamp = "X-Agentry-Timestamp"
	HeaderRun       = "X-Agentry-Run"
)

The headers a webhook carries, beside Content-Type and Authorization.

View Source
const (
	StatusDelivered = "delivered"
	StatusRefused   = "refused"
	StatusFailed    = "failed"

	// Why a file's content was not sent.
	ReasonTooLarge     = "too-large"
	ReasonChanged      = "changed"
	ReasonMissing      = "missing"
	ReasonLink         = "link"
	ReasonUnreadable   = "unreadable"
	ReasonOutside      = "outside-reports"
	ReasonTypeRefused  = "type"
	ReasonDestination  = "destination"
	ReasonCredential   = "credential"
	ReasonAddress      = "address"
	ReasonUnreachable  = "unreachable"
	ReasonTLS          = "tls"
	ReasonTimeout      = "timeout"
	ReasonRedirect     = "redirect"
	ReasonReceiverSaid = "status"
	ReasonStep         = "step"
)

The words a file's outcome and a delivery's reason come in. They are the receipt's closed list (the engine's tests hold the two equal): never a receiver's text, a path or a system's message.

View Source
const DefaultMaxObject int64 = 64 << 20

DefaultMaxObject is the most one object is, in bytes: the largest file a run can write (an exported PDF), so a deliverable the run made is never left out for its size alone.

View Source
const KindS3 = "s3"

KindS3 is a destination that is a bucket of an S3 API: Amazon's, or any other service that speaks it (Cloudflare R2, MinIO, Backblaze B2, Wasabi).

Variables

This section is empty.

Functions

func CheckPrefix

func CheckPrefix(p string) error

CheckPrefix holds a key prefix to what is safe to write on any S3 service: plain segments of letters, digits, '.', '_' and '-', separated by one slash, none empty, '.' or '..', and no slash at either end. An empty prefix is no prefix.

func ObjectKeys

func ObjectKeys(prefix, runID string, paths []string) []string

ObjectKeys makes the key of each deliverable path, <prefix>/<run id>/<path below reports/>, or "" for one it will not name. The agent chose the file's name, so each segment is made plain: a character other than a letter, digit, mark, '.', '_', '-', '(', ')' or a space becomes '_' (a separator, control, format, bidirectional and invisible character among them), leading and trailing spaces and dots go, and a segment with nothing left is "deliverable". The key can therefore never leave the prefix and run folder, whatever the path says. Two paths that become one key keep both, the later one as "name (2).ext". A path that is not beneath reports/, or a key past 1,024 bytes, is "". The run id must be ValidRunID and the prefix CheckPrefix, or every key is "".

func SameService

func SameService(a, b S3Target) bool

SameService says two checked destinations are the same service for the purpose of keeping a credential saved for the first: both Amazon's (an access key reaches every bucket and region of its account), or both the same endpoint, scheme and rule.

func Sign

func Sign(secret []byte, timestamp string, body []byte) string

Sign is the signature over a body: the hex HMAC-SHA256, keyed by the secret, of the timestamp, a full stop and the body. A receiver recomputes it from the X-Agentry-Timestamp header and the raw body, compares in constant time, and refuses a timestamp more than a few minutes from its own clock.

func ValidAccessKeyID

func ValidAccessKeyID(s string) bool

ValidAccessKeyID says whether s can be an access key id.

func ValidHeaderValue

func ValidHeaderValue(v string) bool

ValidHeaderValue says whether v can be an HTTP header value as the step sends it: no control character but a tab, and no DEL.

func ValidRunID

func ValidRunID(s string) bool

ValidRunID says whether s can be the run segment of an object key: the runner's own id, never anything that reads as a path.

func ValidSecret

func ValidSecret(s string) bool

ValidSecret says whether s can sign a body: not empty, valid UTF-8 (it crosses a JSON document and a keychain, which would otherwise change it), and a plain line.

Types

type Credential

type Credential struct {
	Secret          string `json:"secret,omitempty"`
	Authorization   string `json:"authorization,omitempty"`
	AccessKeyID     string `json:"accessKeyId,omitempty"`
	SecretAccessKey string `json:"secretAccessKey,omitempty"`
}

Credential is what arrives on stdin: the HMAC secret signing a webhook's body and the value of an Authorization header the receiver wants, when it does; or a bucket's access key id and secret access key.

func ReadCredential

func ReadCredential(r io.Reader) (Credential, error)

ReadCredential reads the credential from r, which carries nothing else.

type File

type File struct {
	Path   string `json:"path"`
	Title  string `json:"title"`
	SHA256 string `json:"sha256"`
	Bytes  int64  `json:"bytes"`
	Type   string `json:"type"`
	Marked bool   `json:"marked"`
	// Staged names the file in the staging folder, holding the bytes the
	// caller found equal to SHA256. Empty when the caller sends none.
	Staged string `json:"staged,omitempty"`
	// Omitted says why the caller sends no content for the file (one of the
	// Reason words), and the body carries the word.
	Omitted string `json:"omitted,omitempty"`
}

File is one deliverable of the run.

type FileResult

type FileResult struct {
	Path   string `json:"path"`
	Status string `json:"status"`
	Error  string `json:"error,omitempty"`
}

FileResult is one file's outcome.

type Job

type Job struct {
	Kind string `json:"kind"`
	// URL is the destination's address, OnMyNetwork its saved "On my network".
	URL         string `json:"url"`
	OnMyNetwork bool   `json:"onMyNetwork,omitempty"`
	// RunID, Ref and Digest identify the run and the exact release that ran.
	RunID  string `json:"runId"`
	Ref    string `json:"ref"`
	Digest string `json:"digest"`
	// Result is the run's final result as its envelope holds it: the parsed
	// JSON a release with an output schema gave, else its text as a JSON string.
	Result json.RawMessage `json:"result,omitempty"`
	// MaxBody is the body's cap in bytes; zero is DefaultMaxBody.
	MaxBody int64 `json:"maxBody,omitempty"`
	// Bucket, Prefix, Region and Endpoint are a bucket destination's fields
	// (KindS3), URL being empty for it, and MaxObject the most one object is,
	// zero being DefaultMaxObject.
	Bucket    string `json:"bucket,omitempty"`
	Prefix    string `json:"prefix,omitempty"`
	Region    string `json:"region,omitempty"`
	Endpoint  string `json:"endpoint,omitempty"`
	MaxObject int64  `json:"maxObject,omitempty"`
	Files     []File `json:"files"`
}

Job is what the caller asks of the step, written to JobFile.

func ReadJob

func ReadJob(dir string) (Job, error)

ReadJob reads the job under dir, a regular file within a bound. The job folder is read-only to this container (see the package comment), so it is held with os.Root.

type Options

type Options struct {
	Job Job
	// Staging is the read-only folder the job's staged files are in.
	Staging string
	// Work is the folder the report is written to.
	Work string
	Cred Credential
	// Proxy is the CONNECT proxy the POST goes through; nil is a direct
	// connection (tests only).
	Proxy *url.URL
	// Budget bounds a bucket delivery as a whole; zero is the default.
	Budget time.Duration
	// Now is the clock the timestamp reads, nil is time.Now.
	Now func() time.Time
	// Transport replaces the HTTP transport (tests only).
	Transport http.RoundTripper
	// RootCAs replaces the system's roots (tests only).
	RootCAs *x509.CertPool
	// contains filtered or unexported fields
}

Options is one delivery.

type Report

type Report struct {
	Schema string `json:"schema"`
	Kind   string `json:"kind"`
	// Host is the host and port reached.
	Host string `json:"host"`
	// Status is StatusDelivered or StatusFailed for the POST as a whole, Error
	// the closed reason when it failed.
	Status string `json:"status"`
	Error  string `json:"error,omitempty"`
	// Files is each of the job's files in its order, with what became of it.
	Files []FileResult `json:"files"`
	// Result is the outcome of the run's result: sent in the body, or why not.
	Result string `json:"result,omitempty"`
}

Report is what one delivery did, written to ReportFile.

func Run

func Run(ctx context.Context, o Options) (Report, error)

Run delivers one job and writes its report to Work. The error is for a delivery that could not be reported; a delivery that failed is a report.

type S3Spec

type S3Spec struct {
	// Bucket and Prefix name where objects go: <Bucket>/<Prefix>/<run>/<file>.
	// The prefix may be empty.
	Bucket string
	Prefix string
	// Region is the signing region ("us-east-1", or "auto" for R2).
	Region string
	// Endpoint is the service's address when it is not Amazon's; empty is
	// Amazon S3 in Region. OnMyNetwork lets an endpoint be on the person's own
	// network, and http.
	Endpoint    string
	OnMyNetwork bool
}

S3Spec is a bucket destination's non-secret fields.

type S3Target

type S3Target struct {
	S3Spec
	// Scheme is https, or http for an endpoint on the person's own network.
	Scheme string
	// Host is the Host header (and the signed host), HostPort the pair a proxy's
	// allowlist writes.
	Host     string
	HostPort string
	// PathStyle says the bucket is the first path segment, which every
	// endpoint a person names takes; Amazon's own is addressed by host name.
	PathStyle bool
	// Plain says the address is http.
	Plain bool
}

S3Target is a bucket destination checked: the address requests go to and what the proxy in front of them must permit.

func CheckS3

func CheckS3(s S3Spec) (S3Target, error)

CheckS3 holds a bucket destination to its rules and answers where requests for it go. The bucket is a DNS-style name; the region and prefix are plain; Amazon's own address is made from the bucket and region, never typed, and an endpoint takes the webhook's address rule (CheckURL) with no path or query, so it is judged as a webhook's address is: https on port 443, at a public address, unless it is on the person's own network.

type Target

type Target struct {
	// URL is the address to post to, as given and parsed.
	URL *url.URL
	// Host is the host in lower case, Port its port (443 unless the person
	// named another on their own network), HostPort the pair as a proxy's
	// allowlist writes it.
	Host     string
	Port     string
	HostPort string
	// Plain says the address is http, which only a destination on the
	// person's own network may be.
	Plain bool
}

Target is a destination's address checked: where the delivery goes and what the proxy in front of it must permit.

func CheckURL

func CheckURL(raw string, onMyNetwork bool) (Target, error)

CheckURL holds a destination's address to what a webhook may be. It is the one rule: the CLI applies it when a destination is saved and again before a delivery, and the delivery step applies it once more. https, a plain ASCII host name or an IPv4 address, no credentials in the address, no fragment, no space or control character; port 443 only, unless the destination was saved with "On my network" (onMyNetwork), which also admits http and any port. An address that names this machine's own loopback is refused, since in the delivery step that is the step's own container. A name that merely looks like a number (2130706433, 0x7f.1, 127.1) is refused: it is no host name, and some resolvers read it as an address. A literal address is judged here, public for an ordinary destination and public or on the person's own network for the other; a name is judged by the proxy, at the address it resolves to.

Jump to

Keyboard shortcuts

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