Documentation
¶
Overview ¶
Package runnerfiles transfers versioned files between the controller and standalone runners. Shared plans instead require explicitly provisioned direct storage mappings and are forbidden on the snapshot HTTP endpoints.
Index ¶
- Constants
- Variables
- func Handler(store *Store, authorize Authorize, commit CommitGuard) http.Handler
- type Authorize
- type Client
- type CommitGuard
- type Entry
- type Mount
- type Plan
- type Store
- func (s *Store) Lease(m Mount, p, owner string, ttl time.Duration) (string, error)
- func (s *Store) Manifest(ctx context.Context, m Mount) ([]Entry, error)
- func (s *Store) Put(ctx context.Context, m Mount, p, expected, digest string, mode uint32, ...) (Entry, error)
- func (s *Store) Read(m Mount, p, expected string, w io.Writer) (Entry, error)
- func (s *Store) ReadContext(ctx context.Context, m Mount, p, expected string, w io.Writer) (Entry, error)
- func (s *Store) Unlock(m Mount, p, owner, token string) error
- type Syncer
Constants ¶
const MaxSnapshotBytes int64 = 1 << 30
const MaxSnapshotEntries = 20000
const MaxSnapshotFiles = 10000
Snapshot preparation is deliberately bounded. Large/long-lived workspaces use shared storage or explicitly narrowed inputs instead of unbounded copies.
const Missing = "missing"
Variables ¶
var ( ErrConflict = errors.New("file changed since the downloaded version") // SourceBusy means no conflicting publication happened: a source changed // while being snapshotted. Retry file synchronization, never the tool command. ErrSourceBusy = fmt.Errorf("source file is changing; retry synchronization: %w", ErrConflict) ErrLocked = errors.New("file is leased by another execution") ErrPath = errors.New("invalid or unauthorized file path") ErrDigest = errors.New("file digest does not match") ErrLimit = errors.New("snapshot transfer limit exceeded; narrow inputs or use shared storage") )
ErrUnavailable is a bounded, retryable file transport failure. It does not authorize replaying tool calls or ignoring a conflicting file version.
Functions ¶
Types ¶
type Client ¶
type Client struct {
BaseURL string // controller origin, without /runner/v1/files
Credential string
HTTP *http.Client
IdleTimeout time.Duration // default one minute without transfer progress
}
type Mount ¶
type Mount struct {
Name string `json:"name"`
Source string `json:"source"`
Target string `json:"target"`
Writable []string `json:"writable,omitempty"`
}
Source belongs to the controller; a runner must never interpret it as a host mount. Target is the absolute path presented inside its execution sandbox.
type Store ¶
type Store struct {
MaxBytes int64
MaxFiles int
MaxTotalBytes int64
MaxEntries int
Now func() time.Time
// contains filtered or unexported fields
}
Store serializes publication within one controller. Atomic rename means readers see complete files; compare-and-swap prevents lost updates between runners. A single controller owns the workspace (matching ARTEX's existing architecture).
func (*Store) Put ¶
func (s *Store) Put(ctx context.Context, m Mount, p, expected, digest string, mode uint32, owner, lease string, body io.Reader, commitGuard func(func() error) error) (Entry, error)
Put validates an entire upload before acquiring the publication lock. A failed upload, canceled context, stale lease, or digest mismatch never replaces data. authorize is rechecked under the lock immediately before commit to fence a runner whose execution was revoked while it was uploading.
func (*Store) Read ¶
Read pins the version before sending any bytes. The immutable snapshot also prevents in-place local writes from corrupting an otherwise valid download.
func (*Store) ReadContext ¶
type Syncer ¶
type Syncer struct {
Client *Client
Session string
Plan Plan
Roots map[string]string // mount name -> runner host cache, NOT sandbox target
// contains filtered or unexported fields
}
Syncer owns one attempt's private host cache. Calls are serialized. Files are only published after their complete bytes have been verified; a conflict is an error, never last-writer-wins. Remote deletions do not erase local work.
func (*Syncer) Checkpoint ¶ added in v0.6.0
Checkpoint publishes stable files while commands may still be writing others. A real remote version conflict is still fatal. Close always uses strict Push.
func (*Syncer) PullReadOnly ¶
PullReadOnly refreshes peer artifacts without replacing this execution's writable files. Use after the initial Pull, while commands may be running.
Source Files