remote

type AuthMode ¶

type AuthMode string

AuthMode names a supported Rack authentication scheme.

const (
	// AuthModeBearer authenticates with a bearer token.
	AuthModeBearer AuthMode = "bearer"
	// AuthModeAPIKey authenticates with a static API key.
	AuthModeAPIKey AuthMode = "api_key"
)

type BranchCreateRequest ¶

type BranchCreateRequest struct {
	Name         string `json:"name"`
	SourceBranch string `json:"sourceBranch,omitempty"`
	SourceCommit string `json:"sourceCommit,omitempty"`
}

BranchCreateRequest describes a new remote branch to create. Exactly one of SourceBranch or SourceCommit must be set, matching the local branch.Source contract.

type BranchListEntry ¶

type BranchListEntry struct {
	Name       string `json:"name"`
	HeadCommit string `json:"headCommit"`
	Default    bool   `json:"default,omitempty"`
}

BranchListEntry is one branch in a BranchListResult.

type BranchListResult ¶

type BranchListResult struct {
	Branches []BranchListEntry `json:"branches"`
}

BranchListResult is Rack's response to a remote branch list request.

func ListBranches(ctx context.Context, client *Client, cfg Config, credential string) (BranchListResult, error)

type BranchResult ¶

type BranchResult struct {
	Name       string `json:"name"`
	HeadCommit string `json:"headCommit"`
}

BranchResult identifies a remote branch and the wire commit ID it currently points at.

func CreateBranch(ctx context.Context, client *Client, cfg Config, credential string, req BranchCreateRequest) (BranchResult, error)

func DefaultBranch(ctx context.Context, client *Client, cfg Config, credential string) (BranchResult, error)

type Client ¶

type Client struct {
	HTTPClient *http.Client
	// CorrelationID is sent as CorrelationIDHeader on every request this
	// Client issues. Callers should construct one Client per CLI command
	// invocation (via NewClient) and reuse it for every remote call that
	// invocation makes, so Rack's audit log can be correlated end to end.
	CorrelationID string
}

Client performs HTTP calls against a configured Rack endpoint.

func NewClient() *Client

type Config ¶

type Config struct {
	// Endpoint is the Rack HTTP(S) base URL.
	Endpoint string `toml:"endpoint"`
	// RepoID is the logical Rack repository/tenant identity.
	RepoID string `toml:"repo_id"`
	// AuthMode selects how credentials for this remote are authenticated.
	AuthMode AuthMode `toml:"auth_mode"`
}

Config is the versioned, non-secret Rack remote configuration persisted in a repository's control state. It never contains credentials.

func (c Config) Validate() error

type Credential ¶

type Credential struct {
	Value  string
	Source CredentialSource
}

Credential is a resolved secret value and the source it came from. It is never persisted to disk.

func ResolveCredential(repoID string, mode AuthMode, opts ResolveOptions) (Credential, error)

type CredentialSource ¶

type CredentialSource string

CredentialSource identifies where a resolved credential came from.

const (
	// CredentialSourceKeychain reports a credential resolved from the OS
	// keychain or secret store.
	CredentialSourceKeychain CredentialSource = "keychain"
	// CredentialSourceEnv reports a credential resolved from an explicit
	// process environment variable.
	CredentialSourceEnv CredentialSource = "env"
	// CredentialSourceInteractive reports a credential resolved from an
	// interactive TTY prompt.
	CredentialSourceInteractive CredentialSource = "interactive"
)

type DivergedError ¶

type DivergedError struct {
	ActualHead    string
	Guidance      string
	CorrelationID string
}

DivergedError reports that the caller's supplied known commit is not an ancestor of Rack's current branch head. ActualHead is Rack's current wire head commit ID for the branch. CorrelationID is the value Rack's audit log recorded for this request.

func (e *DivergedError) Error() string

type FieldReport ¶

type FieldReport struct {
	Local  uint32      `json:"local"`
	Remote *uint32     `json:"remote,omitempty"`
	Status FieldStatus `json:"status"`
}

FieldReport is the negotiated status of one graphcontract version field.

type FieldStatus ¶

type FieldStatus string

FieldStatus reports how a single graphcontract version field compares against this build's constants.

const (
	// FieldStatusMatch reports that the remote's reported version equals
	// this build's constant.
	FieldStatusMatch FieldStatus = "match"
	// FieldStatusMismatch reports that the remote's reported version
	// differs from this build's constant.
	FieldStatusMismatch FieldStatus = "mismatch"
	// FieldStatusUnknown reports that the remote's response omitted the
	// field, so no comparison could be made.
	FieldStatusUnknown FieldStatus = "unknown"
)

type KeychainStore ¶

type KeychainStore interface {
	Lookup(service, account string) (string, error)
}

KeychainStore resolves a credential from an OS-native keychain or secret store. Lookup must return ErrCredentialNotFound when no entry exists.

type KeyringStore ¶

type KeyringStore struct{}

KeyringStore resolves credentials from the operating system's native keychain or secret store via github.com/zalando/go-keyring.

func (KeyringStore) Lookup(service, account string) (string, error)

type NonFastForwardError ¶

type NonFastForwardError struct {
	ActualHead    string
	Guidance      string
	CorrelationID string
}

NonFastForwardError reports that Rack rejected a push because the supplied BaseCommit is no longer the branch's actual head. ActualHead is Rack's current wire head commit ID for the branch; Guidance is a human-readable message from Rack explaining the rejection; CorrelationID is the value Rack's audit log recorded for this request.

func (e *NonFastForwardError) Error() string

type PromptFunc ¶

type PromptFunc func(label string) (string, error)

PromptFunc requests a secret value interactively, typically reading hidden input from a TTY. Implementations must return ErrCredentialNotFound (or wrap it) when no interactive input is available, rather than blocking indefinitely.

func TerminalPrompt() PromptFunc

type ProtectedBranchError ¶

type ProtectedBranchError struct {
	Guidance      string
	CorrelationID string
}

ProtectedBranchError reports that Rack refused to delete a branch because it is the repository's protected default branch. CorrelationID lets an operator match this failure against Rack's audit log.

func (e *ProtectedBranchError) Error() string

type PullResult ¶

type PullResult struct {
	UpToDate   bool
	HeadCommit string
	Packs      [][]byte
}

PullResult is the outcome of a successful pull HTTP call. When UpToDate is true, Packs is empty and HeadCommit is the branch's current wire commit ID. Otherwise Packs holds every hash-verified, canonically-framed v2 pack Rack sent, oldest-to-newest, and HeadCommit is the wire commit ID the caller advances to once every pack is installed.

func Pull(ctx context.Context, client *Client, cfg Config, credential string, branch, knownCommit string) (PullResult, error)

type PushCommitRecord ¶

type PushCommitRecord struct {
	ID     string               `json:"id"`
	Commit graphcontract.Commit `json:"commit"`
}

PushCommitRecord is one commit to register with Rack as part of a push, matching Rack's expected `metadata.commits[]` wire shape byte-for-byte.

type PushRequest ¶

type PushRequest struct {
	Branch       string
	BaseCommit   string
	TargetCommit string
	Commits      []PushCommitRecord
	PackHash     string
	PackFormat   uint32
	PackData     []byte
}

PushRequest describes a native push to send to a Rack remote. Branch, BaseCommit, TargetCommit, Commits, PackHash, and PackFormat become the JSON `metadata` multipart part; PackData becomes the binary `pack` part. Callers (the CLI command layer) build this from a repository.PushPack.

type PushResult ¶

type PushResult struct {
	Branch     string `json:"branch"`
	HeadCommit string `json:"headCommit"`
}

PushResult is Rack's success response to a push: the branch that advanced and the wire commit ID it now points at.

func Push(ctx context.Context, client *Client, cfg Config, credential string, req PushRequest) (PushResult, error)

type RackError ¶

type RackError struct {
	Code          string `json:"error"`
	Message       string `json:"message"`
	CorrelationID string `json:"correlationId,omitempty"`
	CurrentHead   string `json:"currentHead,omitempty"`
}

RackError is the decoded form of Rack's JSON error envelope:

{"error": "...", "message": "...", "correlationId": "...", "currentHead": "..."}

Code is a stable, machine-readable identifier; Message is a human-readable description; CorrelationID lets an operator match this failure against Rack's audit log; CurrentHead, when present, is the branch's actual wire head commit ID (populated on conflict/non-fast-forward responses).

func (e *RackError) Error() string

type ResolveOptions ¶

type ResolveOptions struct {
	// Keychain resolves a credential from an OS secret store.
	Keychain KeychainStore
	// Getenv resolves a credential from the process environment. Defaults to
	// os.Getenv when nil via ResolveCredential's caller.
	Getenv func(string) string
	// Prompt resolves a credential interactively as a last resort.
	Prompt PromptFunc
}

ResolveOptions configures ResolveCredential's credential sources. Any field may be nil/zero to skip that source.

type VersionReport ¶

type VersionReport struct {
	PackFormatVersion         FieldReport `json:"packFormatVersion"`
	PackIndexFormatVersion    FieldReport `json:"packIndexFormatVersion"`
	PackManifestFormatVersion FieldReport `json:"packManifestFormatVersion"`
}

VersionReport is the full graphcontract version negotiation result for one remote.

func NegotiateVersions(ctx context.Context, client *Client, cfg Config, credential string) (VersionReport, error)