capture

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MPL-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package capture owns the private job workspace, the single-pass snapshot of source and font files, and filesystem-identity alias protection between the resources of one job.

Snapshots make the bytes that were inspected exactly the bytes that are assembled. They are not a filesystem-wide atomic snapshot: a concurrent writer that edits a source in place can only be detected when the change is observable on the open handle (size or modification time moved, or the byte count read differs from the size first observed).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreatePrivateTemp

func CreatePrivateTemp(dir, pattern string) (*os.File, error)

CreatePrivateTemp creates an exclusive owner-only temporary file before sensitive data is written.

func IsDiskFull

func IsDiskFull(err error) bool

IsDiskFull reports whether err means the volume or the user's quota has no space left.

func OpenRegular

func OpenRegular(path string) (*os.File, error)

OpenRegular opens a named input without blocking on a FIFO and verifies the opened object. Symbolic links to regular files are accepted. The caller owns the returned handle.

Types

type AliasError

type AliasError struct {
	// Path is the resource being added.
	Path string
	// OtherPath is the earlier resource it collides with.
	OtherPath string
	// Role is the role of the resource being added.
	Role Role
	// OtherRole is the role of the earlier resource.
	OtherRole Role
}

AliasError reports two different roles naming the same file.

func (*AliasError) Error

func (e *AliasError) Error() string

Error names both resources and the repair.

type ArtifactTargetError

type ArtifactTargetError struct {
	// Path is the path the caller named.
	Path string
	// Problem says what is wrong with the existing entry.
	Problem string
	// Role is the role the path was given.
	Role Role
}

ArtifactTargetError reports an output or report path that exists but cannot be replaced safely.

func (*ArtifactTargetError) Error

func (e *ArtifactTargetError) Error() string

Error names the path and the problem.

type Captured

type Captured struct {
	// Path is the private copy inside the workspace; later stages read only this file.
	Path string
	// SourcePath is the path that was named, as given.
	SourcePath string
	// Size is the number of bytes copied.
	Size int64
	// SHA256 is the digest of the bytes copied, computed during the single copy pass.
	SHA256 [sha256.Size]byte
	// Source is the filesystem identity of the original file (symbolic links resolved).
	Source Identity
}

Captured describes one private copy of a source or font file.

func (Captured) Digest

func (c Captured) Digest() string

Digest returns the SHA-256 digest as lowercase hexadecimal.

type Identity

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

Identity names one filesystem object independent of the path used to reach it: the device and inode on Unix, the volume serial number and file index on Windows. Hard links, symbolic links and case aliases of one file share an Identity. It is comparable and usable as a map key.

func IdentityOf

func IdentityOf(path string) (Identity, error)

IdentityOf returns the identity of the object path resolves to, following symbolic links. It never opens the path, so it cannot block on a FIFO or device.

func IdentityOfFile

func IdentityOfFile(file *os.File) (Identity, error)

IdentityOfFile identifies the already-open object; a path replacement cannot change this identity.

func (Identity) String

func (i Identity) String() string

String renders the identity as "volume:index" in hexadecimal for reports.

type NotRegularFileError

type NotRegularFileError struct {
	// Path is the path the caller named.
	Path string
	// Kind describes what the path resolved to, for example "a directory" or "a named pipe".
	Kind string
}

NotRegularFileError reports a source that is not a regular file once opened.

func (*NotRegularFileError) Error

func (e *NotRegularFileError) Error() string

Error names the path and what it actually is.

type Registry

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

Registry records every resource of a job and rejects a file used in two roles. Existing files are matched by filesystem Identity, so hard links, symbolic links (resolved for every role but output and report, which may not be symbolic links) and case aliases collide; files that do not exist yet are conservatively matched by their directory identity and Unicode-normalized, case-folded basename, including on case-sensitive filesystems. Input lookup uses one identity-map access. Artifact registration refreshes the small artifact-path set to account for replacement, without scanning inputs. A Registry is safe for concurrent use.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty Registry.

func (*Registry) Add

func (r *Registry) Add(role Role, path string) (Identity, error)

Add records path under role. Inputs (plan, source, font) must exist and are resolved through symbolic links. Output and report paths may be new, but an existing one must be a regular file, not a symbolic link. Adding a file already recorded under a different role returns an *AliasError; repeating a role for the same file is allowed (sources are repeated by design). Re-registering an artifact path updates its object identity after replacement; independently registered artifact aliases and input identities remain protected. It returns the file's Identity when it exists and the zero Identity for a new file.

func (*Registry) ProtectOutput added in v0.2.0

func (r *Registry) ProtectOutput(path string) error

ProtectOutput reserves the intended PDF path and its current identity against other roles. It checks aliases independently of output usability: a failed PDF target must not prevent saving evidence to a distinct safe report. Publication still requires Add and destination checks.

func (*Registry) RetireReport

func (r *Registry) RetireReport(path string) error

RetireReport abandons one failed report destination before publishing a distinct recovery file. Inputs, other artifact paths and conservative name reservations remain protected.

type Role

type Role int

Role is what a file is used for in one job. A file may not hold two different roles.

const (
	// RolePlan is the plan file (not used for inline or stdin plans).
	RolePlan Role = iota + 1
	// RoleSource is an input PDF.
	RoleSource
	// RoleFont is a supplied font file.
	RoleFont
	// RoleOutput is the assembled PDF destination.
	RoleOutput
	// RoleReport is a saved report destination.
	RoleReport
)

The roles a job's files can hold.

func (Role) String

func (r Role) String() string

String names the role for messages.

type ScratchError

type ScratchError struct {
	// Err is the underlying operating-system error.
	Err error
	// Dir is the scratch directory involved.
	Dir string
	// Operation names the failed step, for example "create workspace" or "copy source".
	Operation string
}

ScratchError reports a failure to create, write or remove the job's private scratch files.

func (*ScratchError) Error

func (e *ScratchError) Error() string

Error includes a repair action chosen from the kind of failure.

func (*ScratchError) Unwrap

func (e *ScratchError) Unwrap() error

Unwrap exposes the underlying operating-system error.

type Set

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

Set captures each distinct normalized path of a job once, however many times and from however many goroutines it is requested. Sources and fonts share one Set when they share a Workspace. Normalizing equivalent spellings of one path is the caller's responsibility; the Set keys on the string it is given. A Set is safe for concurrent use.

func NewSet

func NewSet(workspace *Workspace) *Set

NewSet returns an empty Set that copies into workspace.

func (*Set) Capture

func (s *Set) Capture(ctx context.Context, path string) (Captured, error)

Capture returns the private copy of path, copying it on the first request only. Concurrent requests for the same path wait for that one copy; a request whose context ends while waiting returns the context error. A failed capture is remembered, so every request for the path in this job reports the same failure.

type SourceChangedError

type SourceChangedError struct {
	// Path is the path the caller named.
	Path string
}

SourceChangedError reports a source that was observed to change while it was being captured.

func (*SourceChangedError) Error

func (e *SourceChangedError) Error() string

Error tells the caller to retry once the writer is finished.

type SourceError

type SourceError struct {
	// Err is the underlying error.
	Err error
	// Path is the path the caller named.
	Path string
	// Operation names the failed step.
	Operation string
}

SourceError wraps a failure to open, read or inspect a named source.

func (*SourceError) Error

func (e *SourceError) Error() string

Error names the path and the failed step.

func (*SourceError) Unwrap

func (e *SourceError) Unwrap() error

Unwrap exposes the underlying error.

type Workspace

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

Workspace is the owner-only private directory (0700 on Unix; protected owner DACL on Windows) that owns every scratch file of one job: snapshots of sources and fonts, and staged output. Close removes everything it owns. A Workspace is safe for concurrent use.

func NewTemporaryWorkspace

func NewTemporaryWorkspace() (*Workspace, error)

NewTemporaryWorkspace creates the workspace in the operating system's temporary directory, for a check that has no output destination.

func NewWorkspaceBeside

func NewWorkspaceBeside(destination string) (*Workspace, error)

NewWorkspaceBeside creates the workspace in the directory that will receive the published output, so that staged files can be published by a same-filesystem rename. The directory must already exist.

func (*Workspace) Close

func (w *Workspace) Close() error

Close removes the workspace and everything in it. It is safe to call more than once.

func (*Workspace) Dir

func (w *Workspace) Dir() string

Dir returns the absolute-or-as-created path of the private directory.

func (*Workspace) NewPath

func (w *Workspace) NewPath(extension string) string

NewPath returns a not-yet-existing path inside the workspace, for staged output. The name is unique within the workspace and carries the given extension (including the dot, or empty).

func (*Workspace) Snapshot

func (w *Workspace) Snapshot(ctx context.Context, path string) (Captured, error)

Snapshot copies the regular file at path into the workspace once, never modifying the original. Symbolic links are followed. The file is opened without blocking and checked for being a regular file on the open handle, so a FIFO or device substituted after any earlier stat cannot hang the call. The copy is cancellable between chunks and fails with a *SourceChangedError when the size or modification time moves while it is read. No descriptor outlives the call, and partial copies are removed on failure.

Jump to

Keyboard shortcuts

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