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 ¶
- func CreatePrivateTemp(dir, pattern string) (*os.File, error)
- func IsDiskFull(err error) bool
- func OpenRegular(path string) (*os.File, error)
- type AliasError
- type ArtifactTargetError
- type Captured
- type Identity
- type NotRegularFileError
- type Registry
- type Role
- type ScratchError
- type Set
- type SourceChangedError
- type SourceError
- type Workspace
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreatePrivateTemp ¶
CreatePrivateTemp creates an exclusive owner-only temporary file before sensitive data is written.
func IsDiskFull ¶
IsDiskFull reports whether err means the volume or the user's quota has no space left.
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.
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 ¶
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 ¶
IdentityOfFile identifies the already-open object; a path replacement cannot change this identity.
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 (*Registry) Add ¶
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
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 ¶
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.
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 (*Set) Capture ¶
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 ¶
NewTemporaryWorkspace creates the workspace in the operating system's temporary directory, for a check that has no output destination.
func NewWorkspaceBeside ¶
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 ¶
Close removes the workspace and everything in it. It is safe to call more than once.
func (*Workspace) NewPath ¶
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 ¶
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.