file

package
v0.16.2 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package file announces a release by appending it to a structured file in a repository and committing it.

It is the first adapter that can honestly report Unchanged, and the reason is where its idempotency lives: the entry it appends carries a key, and the file it appends to is the record. A retried pipeline re-reads the same file and sees its own previous write, so there is no marker, no database and no lock (spec 0023 D2).

Index

Constants

Name is what this adapter is called in a manifest and in a report.

Variables

View Source
var ErrBadFeed = errors.New("announce: the feed file cannot be appended to")

ErrBadFeed reports a file this adapter cannot append to.

Functions

func IsLocal added in v0.13.0

func IsLocal(repo string) bool

IsLocal reports whether a feed's `repo` names a directory rather than a project: a relative path (`./out`, `../out`) or an absolute one.

Types

type Adapter

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

Adapter appends a release to a file in a repository.

func New

func New(feed manifest.FileFeed, store Store) *Adapter

New builds the adapter from its manifest settings.

func (*Adapter) Announce

func (a *Adapter) Announce(ctx context.Context, r announce.Release) (announce.Status, error)

Announce appends the release, or reports that it is already there.

func (*Adapter) Name

func (a *Adapter) Name() string

Name identifies the adapter.

type Format

type Format string

Format is how a feed file is written.

const (
	// FormatYAML is the default and what the estate uses.
	FormatYAML Format = "yaml"

	// FormatJSON is for a site whose data files are JSON.
	FormatJSON Format = "json"
)

func FormatFor

func FormatFor(declared Format, filePath string) (Format, error)

FormatFor decides how to read a file, preferring what the manifest said and otherwise what the path's extension says.

Inferring rather than requiring, because a `.json` path read as YAML is the dangerous case: JSON is a subset of YAML, so it parses, and the file is rewritten AS YAML on the first release. An extension nobody recognises is refused rather than assumed.

type GitStore

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

GitStore is the Store over git: an in-memory sparse clone of the target repository, a commit, and a push.

Not the forge API, which cannot write a file — go/forge's Contents is GetFile and nothing else (spec 0023 D5).

func NewGitStore

func NewGitStore(settings repo.Settings, host string, author object.Signature) *GitStore

NewGitStore builds the store. host is where the target repository lives, so a relative "owner/name" can be turned into a clone URL.

func (*GitStore) Apply

func (g *GitStore) Apply(ctx context.Context, req Request) (Result, error)

Apply clones, appends and pushes, retrying a rejected push.

func (*GitStore) WithForge

func (g *GitStore) WithForge(provider forge.Provider) *GitStore

WithForge gives the store what the merge-request mode needs. A provider missing either capability is not an error here: the mode reports what it could not do rather than refusing to run.

func (*GitStore) WithRemote

func (g *GitStore) WithRemote(remoteFor func(repo string) string) *GitStore

WithRemote replaces how a target repository is located, which is how a test points the store at a repository on disk.

type LocalStore added in v0.13.0

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

LocalStore writes the feed under a directory instead of a repository: the test seam for the whole path, and a dry run of what the repository would receive (spec 0026 D3). Nothing is committed and nothing is proposed; the merge-request mode behaves as the commit mode.

func NewLocalStore added in v0.13.0

func NewLocalStore(dir string) *LocalStore

NewLocalStore returns a store over dir, which is created on first write.

func (*LocalStore) Apply added in v0.13.0

func (l *LocalStore) Apply(_ context.Context, req Request) (Result, error)

Apply reads the file, hands it to Change, and writes what comes back.

type Request

type Request struct {
	Repo, Branch, Token string
	Path, Message       string

	Mode  manifest.Mode
	Merge manifest.Merge

	// Branch name for the merge-request mode, deterministic per release so a
	// re-run neither collides nor forks (spec 0023 D8).
	Proposed string

	Change func(current []byte) ([]byte, error)
}

Request is one file change.

type Result

type Result struct {
	// Written is false when Change asked for nothing.
	Written bool

	// AlreadyProposed reports a merge request already open from Proposed, which
	// is the merge-request mode's idempotency answer: the entry is not on the
	// target branch until somebody merges, so the file cannot say (D8).
	AlreadyProposed bool

	// Number is the merge request opened, zero in the commit mode.
	Number int

	// NotHonoured names what the forge could not do, empty when it did
	// everything asked.
	NotHonoured string
}

Result says what the store did.

type Store

type Store interface {
	// Apply reads the file at Request.Path and hands its bytes to Change, nil
	// when the file is absent. Change returning nil bytes means nothing to
	// write. What it returns is committed and pushed.
	Apply(ctx context.Context, req Request) (Result, error)
}

Store is the repository work: read the file at the branch, and commit a new version of it.

A seam rather than a call, because the git half and the document half fail in completely different ways and neither should need the other to be tested.

Jump to

Keyboard shortcuts

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