gitproxy

type Credential struct {
	Username string
	Password string
	// GrantID and LeaseID are audit bookkeeping. Neither is secret.
	GrantID string
	LeaseID string
}

type Decision struct {
	Update RefUpdate
	Err    error
}

type DenyReason string

type Event struct {
	Kind      EventKind `json:"kind"`
	SessionID string    `json:"session_id,omitempty"`
	RepoPath  string    `json:"repo_path,omitempty"`
	ProjectID string    `json:"project_id,omitempty"`
	TaskID    string    `json:"task_id,omitempty"`
	Actor     string    `json:"actor,omitempty"`
	// Refs are the ref names the request touched.
	Refs []string `json:"refs,omitempty"`
	// Detail is a human-readable reason or summary.
	Detail string    `json:"detail,omitempty"`
	At     time.Time `json:"at"`
}

type EventKind string

type MintRequest struct {
	// Upstream is the real https repository URL the proxy will forward to.
	Upstream string
	// Credential authenticates the proxy upstream. Optional: a public
	// repository needs none, though pushing to one generally does.
	Credential Credential
	// Policy is what the sandbox may do. Zero value gets WriteBackPolicy.
	Policy Policy
	// TTL bounds the session. 0 means DefaultSessionTTL; anything above
	// MaxSessionTTL is an error rather than a silent clamp, because a caller
	// that asked for a day and got twelve hours would discover it as a failed
	// push halfway through.
	TTL time.Duration

	ProjectID  string
	TaskID     string
	ExecutorID string
	Actor      string
}

type Minted struct {
	Session *Session
	// Token is the plaintext session token. The registry keeps only its hash,
	// so this is the only copy that will ever exist.
	Token string
	// RepoURL is what the sandbox uses as its remote: the proxy's public base
	// with the session's repository path. It carries no credential.
	RepoURL string
}

type Options struct {
	// Transport carries the proxy's requests to the forge. nil gets a
	// hardened default. It exists so an operator whose forge sits behind a
	// private CA can supply one — the same case pkg/tlsconf exists for — and
	// so a test can point the upstream leg at a self-signed fixture without
	// weakening the default.
	Transport http.RoundTripper
}

type Policy struct {
	// AllowedRefs are glob patterns over full ref names. A pattern without a
	// refs/ prefix is read as a branch name and gets refs/heads/ prepended, so
	// "cloop/*" and "refs/heads/cloop/*" mean the same thing.
	//
	// Matching follows path.Match: "*" does not cross a "/". A trailing "/**"
	// matches any depth below the prefix, which is what a per-task namespace
	// like cloop/task-42/fixup needs.
	AllowedRefs []string `json:"allowed_refs,omitempty"`

	// AllowCreate permits a push that brings a ref into existence. Creating a
	// new branch under an allowed namespace is the ordinary write-back case, so
	// this is the one authority a caller almost always wants.
	AllowCreate bool `json:"allow_create,omitempty"`

	// AllowUpdate permits moving an existing allowed ref to a new commit. A
	// retried task legitimately replaces its own predecessor.
	AllowUpdate bool `json:"allow_update,omitempty"`

	// AllowDelete permits removing an allowed ref. Off by default: deleting is
	// not something a write-back ever needs, and a name-only allowlist that
	// forgot about deletes would let a sandbox destroy the very branches it was
	// scoped to.
	AllowDelete bool `json:"allow_delete,omitempty"`

	// AllowFetch permits the read half of the protocol — git-upload-pack — over
	// the same session. A sandbox that clones through the proxy needs it; one
	// that only pushes back a tree it was handed does not.
	AllowFetch bool `json:"allow_fetch,omitempty"`

	// MaxCommands caps ref updates per push. 0 means DefaultMaxCommands.
	MaxCommands int `json:"max_commands,omitempty"`

	// MaxPackBytes caps the request body. 0 means DefaultMaxPackBytes.
	MaxPackBytes int64 `json:"max_pack_bytes,omitempty"`
}

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

type ReceivePack struct {
	// Commands are the ref updates, in wire order.
	Commands []RefUpdate
	// Capabilities are the tokens the client advertised after the NUL on the
	// first command line — "report-status", "side-band-64k", "agent=git/2.43"
	// and so on.
	Capabilities []string
	// Shallow lists the object names from any shallow lines. They are carried
	// so a caller can see them; nothing here decides on them.
	Shallow []string
}

type RefDenial struct {
	Reason  DenyReason
	Message string
}

type RefUpdate struct {
	Old string
	New string
	Ref string
}

type Registry struct {
	// BaseURL is the https base the sandbox reaches the proxy at, e.g.
	// "https://hub.internal:8443". Sessions render their RepoURL beneath it.
	BaseURL string
	// Now is the clock, injectable for tests. nil means time.Now.
	Now func() time.Time
	// OnEvent, if set, receives every authorisation decision. It runs on the
	// request goroutine, so an implementation that blocks blocks a push.
	OnEvent func(Event)
	// contains filtered or unexported fields
}

type Session struct {
	// ID identifies the session and is the username half of the basic
	// credential the sandbox presents. Not secret.
	ID string
	// RepoPath is the "owner/name" the sandbox addresses, and the path the
	// proxy serves this session under. Pinning it means a session minted for
	// one repository cannot be replayed against another the same proxy happens
	// to be serving.
	RepoPath string
	// Upstream is the real https clone URL. It never reaches the sandbox.
	Upstream string
	// Policy is what this session may do.
	Policy Policy

	// Labels for the audit trail.
	ProjectID  string
	TaskID     string
	ExecutorID string
	Actor      string

	IssuedAt  time.Time
	ExpiresAt time.Time
	// contains filtered or unexported fields
}

type Stats struct {
	Pushes    int64 `json:"pushes"`
	Fetches   int64 `json:"fetches"`
	Denied    int64 `json:"denied"`
	BytesUp   int64 `json:"bytes_up"`
	BytesDown int64 `json:"bytes_down"`
}