deliver

package
v0.7.49 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package deliver copies a run's deliverables out of its output folder to a folder the person chose. The output folder is the run's proof and a delivery only reads it: a file is copied, never moved, rewritten or deleted, and only after its bytes are shown to be the ones the envelope's deliverables block names by SHA-256. What the agent wrote stays hostile: the source is reached through an os.Root with no link anywhere in its path, the destination's names are made safe (SafeName), a copy is made under a hidden name and takes its own only once its digest is right, never replacing a file that is already there, a type the system acts on when a folder is merely viewed is not copied, and on Windows and macOS a copy carries the system's flag for a download.

Index

Constants

View Source
const LedgerFile = "deliveries.ndjson"

LedgerFile is the delivery record under the run's receipts, one JSON line (receipt.Delivery) per file per destination.

Variables

This section is empty.

Functions

func AgentName

func AgentName(ref string) string

AgentName is the QuickAgent's name in a release ref (namespace/name@version).

func Label

func Label(files []receipt.Deliverable, runID string) string

Label is what names a run's folder: the title of its one deliverable, or the run id when it has several (or none a title names).

func Locate

func Locate(runDir string, f receipt.Deliverable) (string, error)

Locate checks a deliverable of the run folder runDir the way a delivery does, and gives the absolute path of the file it names. The file must be a regular file under reports/, reached through no link, of a type a file manager does not act on, and its bytes must be the size and SHA-256 the envelope lists. Nothing is written. It is for a client that hands the path to a person or a program, which is why it holds the file to the digest now.

func Read

func Read(runDir string, f receipt.Deliverable, max int64) (string, []byte, error)

Read is Locate and the file's bytes, which it reads once and holds to the digest; a file larger than max is refused (DeliveryErrTooLarge) before any byte is read.

func ReadEnvelope

func ReadEnvelope(runDir string) (*receipt.Envelope, error)

ReadEnvelope reads the run/v1 envelope of a run folder, its result.json.

func Redeliver

func Redeliver(runDir string, o FolderOptions) ([]receipt.Delivery, error)

Redeliver copies the deliverables an existing run folder's envelope lists to the folder in o (Agent, Label and When default from the envelope and the clock) and adds the records to its receipts/deliveries.ndjson. The folder is otherwise untouched. An error is returned only when there is nothing to deliver: a folder that is not a run's, a run that did not succeed, one that lists no deliverable.

func SafeName

func SafeName(s string) string

SafeName turns a name the agent or the publisher chose into one path segment that is safe to create on any system: the same name read back as a single plain file name, never a path, a hidden file or a device. It

  • replaces the path separators and the characters Windows reserves (\ / : * ? " < > |, a colon among them, which would name a stream), every control, format, line-break and bidirectional formatting character (which could make "txt" + U+202E + "fdp.exe" read as a PDF) and every other character that does not print, each with an underscore;
  • drops leading and trailing spaces and dots (a leading dot hides a file, a trailing one is dropped by Windows, and ".." is no name);
  • puts an underscore before a reserved Windows device name (CON, PRN, AUX, NUL, COM0 to COM9, LPT0 to LPT9, with any extension);
  • shortens a long name, keeping a short extension.

A name with nothing left is "deliverable".

func ToFolder

func ToFolder(runDir string, files []receipt.Deliverable, o FolderOptions) []receipt.Delivery

ToFolder copies each file of a run's deliverables from runDir to the folder o names, and returns one record per file. It never fails the caller: a file that was refused or could not be written is a record with a status and a closed reason, and the others are still copied.

func WriteLedger

func WriteLedger(runDir string, ds []receipt.Delivery, appendTo bool) error

WriteLedger records deliveries in the run's receipts/deliveries.ndjson, one JSON line each. With appendTo false the file is made new, as a run does for its own; with it true the lines are added, as a later delivery of a run folder does, which leaves every other file of the folder, result.json included, as it was.

Types

type FolderOptions

type FolderOptions struct {
	// Root is the folder the person chose, an absolute path. It is created
	// when it does not exist.
	Root string
	// Agent is the QuickAgent's name (AgentName), Label the title of the one
	// deliverable or else the run id (Label).
	Agent string
	Label string
	// When is the time in the folder's name; zero is now.
	When time.Time
}

FolderOptions says where a run's deliverables go and what the folder is called: <Root>/<Agent>/<When as YYYY-MM-DD HHmm> <Label>/.

type ReadError

type ReadError struct{ Reason string }

ReadError is why a deliverable could not be read: one of receipt's closed words (DeliveryErrChanged, DeliveryErrMissing, DeliveryErrOutside, DeliveryErrLink, DeliveryErrUnreadable, DeliveryErrType, DeliveryErrTooLarge).

func (*ReadError) Error

func (e *ReadError) Error() string

type Staged

type Staged struct {
	Name   string
	Reason string
}

Staged is what became of one deliverable on its way to a staging folder: the name of the verified copy there, or the closed reason there is none.

func Stage

func Stage(runDir string, files []receipt.Deliverable, dir string, budget int64) []Staged

Stage copies deliverables from the run folder into dir, as many as a body of budget bytes can carry (each file counts as the base64 of its bytes, which is how a webhook sends it), in order, and no more: a file that does not fit in what is left is not staged, whatever follows it. Each copy is made (which must exist), under names of the runner's own (f0000, f0001, …), and answers one Staged per file in order. A file is staged only as a delivery to a folder would copy it: read through no link, from beneath reports/, and shown to be the bytes of the envelope's size and SHA-256 as they are copied. A destination that sends a file reads the staged copy, never the run folder, so a file the agent changes after the check is never the one sent, and the step that holds the destination's credential sees no path of the run folder at all. The copies are 0600: they are the person's alone.

func StageRaw

func StageRaw(runDir string, files []receipt.Deliverable, dir string, perFile, total int64) []Staged

StageRaw is Stage for a destination that sends each file as it is (a bucket's object): a file is staged when it is no larger than perFile, and as many as total bytes hold, in order. It makes the same checks and the same copies.

Jump to

Keyboard shortcuts

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