Documentation
¶
Overview ¶
Package publish is `anfra publish`: a local repo's files published to its org, as PUBLISH.md (anfra-cloud) describes. The command wires it to the terminal (Env); its messages name the command's flags.
Index ¶
- func Confirm(ask Prompt, question string) (yes, ok bool)
- func Run(ctx context.Context, dir string, o Options, env Env) (any, error)
- type CheckResult
- type Env
- type FileChange
- type Input
- type MotherDuck
- type Options
- type OrgRef
- type Prompt
- type PullConflict
- type PullOptions
- type PullResult
- type Pulled
- type Result
- type StatusResult
- type TakenSide
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CheckResult ¶ added in v0.17.0
type CheckResult struct {
Message string `json:"message" doc:"the outcome, in a sentence"`
Org *OrgRef `json:"org" doc:"where it would be published. Null when no org is configured."`
Files []string `json:"files" doc:"the files it would send" pretty:",tree"`
Hints []string `json:"hints,omitempty" doc:"what to do next, if any"`
}
CheckResult is `publish check`'s result: what would be published, and where (docs/designs/commands-and-api.md#cli-output).
type Env ¶
type Env struct {
// ErrOut is where progress and questions go, for a person at a terminal.
ErrOut io.Writer
// Warn says a problem that doesn't stop the publish, by its code; nil says
// nothing.
Warn func(code, message string)
// OrgName is an org's name, as its login knows it; nil, or "": unknown.
OrgName func(cloudapi.Org) string
Ask Prompt
// Validate validates the repo here, before anything is sent: an error
// refusing the publish, carrying what fails. Always, and again on the
// server, whose verdict on exactly the published files is the one that
// publishes (PUBLISH.md §Decisions).
Validate func(context.Context) error
// Credential checks the selected login before destination configuration is
// saved, returning an authorizer that resolves credentials for every request.
Credential func(context.Context, cloudapi.Org) (func(*http.Request) error, error)
// SelectOrg explicitly selects a first destination; nil means no interactive terminal.
SelectOrg func(context.Context) (cloudapi.Org, error)
// RecoverOrg offers interactive recovery after credential loading fails.
// It must return the original error when recovery does not apply, and confirm
// any destination change before returning a different organization.
RecoverOrg func(context.Context, cloudapi.Org, error) (cloudapi.Org, error)
// UserAgent names the CLI and its version, for the server.
UserAgent string
// MotherDuck is the person's MotherDuck account, to copy a DuckDB data source
// to; nil offers no copy.
MotherDuck MotherDuck
// Input asks for a line of text, as Ask asks a question; nil with no
// terminal.
Input Input
// Logger is the repo's log, for what the publish absorbed that no one
// sees, such as a retry; nil records nothing.
Logger *slog.Logger
}
Env is what a publish needs from the command around it.
type FileChange ¶ added in v0.20.0
type FileChange struct {
Path string `json:"path" doc:"the file's path in the repo"`
Change string `` /* 216-byte string literal not displayed */
}
FileChange is a file a pull changed, or one a pull or a publish would change.
type Input ¶ added in v0.13.0
Input asks for a line of text, and returns it trimmed: "" when nothing was typed, or the question was interrupted; ok is false when nobody can answer it.
type MotherDuck ¶ added in v0.13.0
type MotherDuck interface {
Find(ctx context.Context) (version string, ok bool)
Status(ctx context.Context) (motherduck.Status, error)
Login(ctx context.Context) error
Session(ctx context.Context) (token string, databases []string, err error)
DatabaseExists(ctx context.Context, name string) (bool, error)
CreateDatabaseFrom(ctx context.Context, name, path string) error
CreateReadToken(ctx context.Context, session, username, name, description string) (motherduck.Token, error)
RevokeToken(ctx context.Context, session, username, id string) error
}
MotherDuck is a person's MotherDuck account, as copying a DuckDB file there needs it (motherduck.Account). Nil offers no copy: without a terminal, nobody is there to sign in.
type Options ¶
type Options struct {
// Message is what the publish is, for the org's history of the repo; "" is
// HEAD's commit, in a git repo.
Message string
// SetOrg is an org's address to record as the repo's, and publish to.
SetOrg string
// Check is publish check: the preflight, which goes as far as a publish
// would before its first change, then says what it would do. Today, the
// part done here, offline, without authentication or config writes: the
// files, and where they'd go.
Check bool
// Pull merges what the org has that this folder hasn't seen before
// publishing, instead of refusing; it stops on conflicts.
Pull bool
// Yes did nothing since publish stopped asking before replacing a
// version; kept for a release, with a warning.
Yes bool
// CreateDataSources adds the data sources the repo uses and the org lacks
// without asking.
CreateDataSources bool
}
Options are a publish's choices: the command's flags.
type OrgRef ¶ added in v0.17.0
type OrgRef struct {
URL string `json:"url" doc:"the org's address"`
Name string `json:"name,omitempty" doc:"the org's name, from its saved login. Absent when it isn't known."`
}
OrgRef is an org a publish goes to: its address, and its name when the login knows it.
type Prompt ¶
Prompt asks a question with choices, the last one the default (the safe answer), and returns the choice's index; ok is false when nobody can answer it (not a terminal).
type PullConflict ¶ added in v0.20.0
type PullConflict struct {
Paths []string `` /* 161-byte string literal not displayed */
Message string `json:"message" doc:"what happened, naming its files"`
}
PullConflict is one conflict: the paths it covers, and what happened.
type PullOptions ¶ added in v0.20.0
type PullOptions struct {
// SetOrg is an org's address to record as the repo's, and pull from.
SetOrg string
// Take is "org" or "local": resolve the conflicts on Paths by keeping that
// side's version of the whole files.
Take string
Paths []string
// Abort undoes the last pull while it isn't finished.
Abort bool
}
PullOptions are a pull's choices: the command's flags. At most one of Take and Abort.
type PullResult ¶ added in v0.20.0
type PullResult struct {
Message string `json:"message" doc:"the outcome, in a sentence"`
Org *OrgRef `json:"org,omitempty" doc:"the org pulled from"`
Revision string `json:"revision,omitempty" doc:"the org's revision this pull merged into the folder"`
PublishedBy string `json:"published_by,omitempty" doc:"who published that revision. Absent for the org's starting files."`
PublishedAt *time.Time `json:"published_at,omitempty" doc:"when that revision was published" pretty:",moment"`
Base string `json:"base,omitempty" doc:"the org's revision this folder matched before the pull. Absent when anfra had no record of one."`
Changes []FileChange `json:"changes,omitempty" doc:"the files the pull wrote or deleted, other than those with conflicts"`
Conflicts map[string][]PullConflict `` /* 192-byte string literal not displayed */
HowToResolve map[string]string `json:"how_to_resolve,omitempty" doc:"how to resolve each kind of conflict left, by kind"`
Taken []TakenSide `json:"taken,omitempty" doc:"with --take: the conflicts resolved, and the side kept"`
Restored []string `json:"restored,omitempty" doc:"with --abort: the files put back as they were before the pull"`
Hints []string `json:"hints,omitempty" doc:"what to do next, if any"`
}
PullResult is a pull's result: what it merged into the folder, and what's left to resolve. --take and --abort answer it too, with what they did.
func Pull ¶ added in v0.20.0
func Pull(ctx context.Context, dir string, o PullOptions, env Env) (PullResult, error)
Pull merges the org's published files into the folder at dir, or, with o.Take or o.Abort, resolves or undoes the last pull (docs/designs/publish.md).
type Pulled ¶ added in v0.20.0
type Pulled struct {
Revision string `json:"revision" doc:"the org's revision pulled"`
PublishedBy string `json:"published_by,omitempty" doc:"who published it. Absent for the org's starting files."`
PublishedAt *time.Time `json:"published_at,omitempty" doc:"when it was published" pretty:",moment"`
Changes []FileChange `json:"changes" doc:"the files the pull wrote or deleted"`
}
Pulled is what publish --pull merged into the folder before publishing.
type Result ¶ added in v0.17.0
type Result struct {
Message string `json:"message" doc:"the outcome, in a sentence"`
Org OrgRef `json:"org" doc:"where it was published"`
Revision string `json:"revision" doc:"the revision published"`
Changed bool `json:"changed" doc:"false when these files were what the org had published"`
Replaced *cloudapi.Replaced `json:"replaced,omitempty" doc:"the revision it replaced"`
Files int `json:"files" doc:"how many files it published"`
DataSourcesCreated []string `json:"data_sources_created" doc:"the data sources it added to the org"`
Pulled *Pulled `` /* 126-byte string literal not displayed */
Hints []string `json:"hints,omitempty" doc:"what to do next, if any"`
}
Result is a publish's result: the revision it published, and what came of it.
type StatusResult ¶ added in v0.20.0
type StatusResult struct {
Message string `json:"message" doc:"the outcome, in a sentence"`
Org *OrgRef `json:"org,omitempty" doc:"the repo's org. Absent when none is configured."`
Revision string `json:"revision,omitempty" doc:"the org's published revision"`
PublishedBy string `json:"published_by,omitempty" doc:"who published that revision. Absent for the org's starting files."`
PublishedAt *time.Time `json:"published_at,omitempty" doc:"when that revision was published" pretty:",moment"`
Base string `json:"base,omitempty" doc:"the org's revision this folder last pulled or published. Absent when anfra has no record of one."`
Incoming []FileChange `json:"incoming,omitempty" doc:"what the org changed since the base: what a pull would change in this folder"`
Unpublished []FileChange `` /* 128-byte string literal not displayed */
// PullInterrupted is a pull stopped partway through writing files: the
// folder is half pulled, so it isn't compared.
PullInterrupted bool `` /* 146-byte string literal not displayed */
Conflicts map[string][]PullConflict `json:"conflicts,omitempty" doc:"the last pull's conflicts not resolved yet, by kind"`
HowToResolve map[string]string `json:"how_to_resolve,omitempty" doc:"how to resolve each kind of conflict left, by kind"`
Hints []string `json:"hints,omitempty" doc:"what to do next, if any"`
}
StatusResult is `publish status`'s result: how this folder stands against what its org has published.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package syncstate keeps a repo folder's sync state with its orgs: the org revision its files last matched (the base), and a pull that isn't finished (the pending record).
|
Package syncstate keeps a repo folder's sync state with its orgs: the org revision its files last matched (the base), and a pull that isn't finished (the pending record). |
|
Package workdir is a repo folder as publish and pull see it: the files a publish carries, hashed into a tree, and the safe writing of a merge into them, with a backup to undo it.
|
Package workdir is a repo folder as publish and pull see it: the files a publish carries, hashed into a tree, and the safe writing of a merge into them, with a backup to undo it. |