Git designed for AI agents.
package gitcmd
import (
"context"
"crypto/rand"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"sort"
"strings"
"github.com/feder-cr/git-ai/internal/featureflag"
"github.com/feder-cr/git-ai/internal/git"
"github.com/feder-cr/git-ai/internal/git/mvcc"
"github.com/feder-cr/git-ai/internal/gitaly/config"
"github.com/feder-cr/git-ai/internal/gitaly/storage"
"github.com/feder-cr/git-ai/internal/graft/changelog"
"github.com/feder-cr/git-ai/internal/graft/identity"
"github.com/feder-cr/git-ai/internal/graft/policystore"
"github.com/feder-cr/git-ai/internal/grpc/metadata"
"github.com/feder-cr/git-ai/internal/log"
"github.com/feder-cr/git-ai/internal/transaction/txinfo"
"github.com/feder-cr/git-ai/proto/go/gitalypb"
"google.golang.org/protobuf/encoding/protojson"
)
const (
// EnvHooksPayload is the name of the environment variable used
// to hold the hooks payload.
EnvHooksPayload = "GITALY_HOOKS_PAYLOAD"
)
// ErrPayloadNotFound is returned by HooksPayloadFromEnv if the given
// environment variables don't have a hooks payload.
var ErrPayloadNotFound = errors.New("no hooks payload found in environment")
// Hook represents a git hook. See githooks(5) for more information about
// existing hooks.
type Hook uint
const (
// ReferenceTransactionHook represents the reference-transaction git hook.
ReferenceTransactionHook = Hook(1 << iota)
// UpdateHook represents the update git hook.
UpdateHook
// PreReceiveHook represents the pre-receive git hook.
PreReceiveHook
// PostReceiveHook represents the post-receive git hook.
PostReceiveHook
// PackObjectsHook represents the pack-objects git hook.
PackObjectsHook
// AllHooks is the bitwise set of all hooks supported by Gitaly.
AllHooks = ReferenceTransactionHook | UpdateHook | PreReceiveHook | PostReceiveHook | PackObjectsHook
// ReceivePackHooks includes the set of hooks which shall be executed in
// a typical "push" or an emulation thereof (e.g. `updateReferenceWithHooks()`).
ReceivePackHooks = ReferenceTransactionHook | UpdateHook | PreReceiveHook | PostReceiveHook
)
// FeatureFlagWithValue is used as part of the HooksPayload to pass on feature flags with their
// values to gitaly-hooks.
type FeatureFlagWithValue struct {
// Flag is the feature flag.
Flag featureflag.FeatureFlag `json:"flag"`
// Enabled indicates whether the flag is enabled or not.
Enabled bool `json:"enabled"`
}
// HooksPayload holds parameters required for all hooks.
type HooksPayload struct {
// RequestedHooks is a bitfield of requested Hooks. Hooks which
// were not requested will not get executed.
RequestedHooks Hook `json:"requested_hooks"`
// FeatureFlagsWithValue contains feature flags with their values. They are set into the
// outgoing context when calling HookService.
FeatureFlagsWithValue []FeatureFlagWithValue `json:"feature_flags_with_value,omitempty"`
// Repo is the repository in which the hook is running.
Repo *gitalypb.Repository `json:"-"`
// ObjectFormat is the object format used by the repository. Some hooks use it in order to
// verify object IDs part of their input.
ObjectFormat string `json:"object_format"`
// RuntimeDir is the path to Gitaly's runtime directory.
RuntimeDir string `json:"runtime_dir"`
// InternalSocket is the path to Gitaly's internal socket.
InternalSocket string `json:"internal_socket"`
// InternalSocketToken is the token required to authenticate with
// Gitaly's internal socket.
InternalSocketToken string `json:"internal_socket_token"`
// Transaction is used to identify a reference transaction. This is an optional field -- if
// it's not set, no transactional voting will happen.
Transaction *txinfo.Transaction `json:"transaction"`
// UserDetails contains information required when executing
// git-receive-pack or git-upload-pack
UserDetails *UserDetails `json:"user_details"`
// GitalyClientContext contains the context passed through the RPCs.
GitalyClientContext []byte `json:"gitaly_client_context,omitempty"`
// StoragePreparing asks gitaly-hooks to forward the "preparing" state of
// the reference-transaction hook to the server. It is set when the Graft
// storage core is authoritative, whose write path builds and uploads the
// pack of a transaction before git takes the reference locks
// (doc/graft/PLAN6.md, LOCK AND HISTORY RULE). Otherwise the state is not
// forwarded, as upstream: Praefect votes would change, and authoritative
// mode is not supported behind Praefect.
StoragePreparing bool `json:"storage_preparing,omitempty"`
// LogFields contains the log fields in the current context. They are passed
// to the HookService so the calls can be correlated with the main RPC call.
LogFields log.Fields
// Changelog is the changeset log metadata of the reference updates, taken
// from the context that built the payload. Env writes it into the environment
// and ChangelogMetaFromEnv reads it back. HooksPayloadFromEnv deliberately
// does not restore it, so a decoded payload only holds the upstream fields
// and still compares equal to them.
Changelog ChangelogMeta `json:"-"`
}
// ChangelogMeta describes the changeset log entries of the reference updates
// performed with a hooks payload. It is taken from the context of the request
// that builds the payload.
type ChangelogMeta struct {
// Operation is the operation that performs the updates, empty when it cannot
// be derived from the context.
Operation string `json:"operation,omitempty"`
// Actor is the authenticated identity that performs the updates. Empty when
// there is none, in which case the recording hook falls back to the user ID.
Actor string `json:"actor,omitempty"`
// Agent is true when Actor was authenticated with a per-agent token. The
// standalone access policy then decides on Actor instead of the
// client-supplied user ID, so an agent cannot act as another one.
Agent bool `json:"agent,omitempty"`
// Rewritten is true when the updates rewrite history.
Rewritten bool `json:"rewritten,omitempty"`
// Invocation identifies the git process that runs the reference-transaction
// hook with this payload, or the call of updateref.UpdaterWithHooks that drives
// the hook in process. It is a random value set for each git command that git
// runs the hook for and for each such call, so the recording hook can tell the
// transactions of one process apart from those of concurrent processes, also
// when they have the same updates. Git runs two transactions to delete a
// packed reference, and the recording hook pairs them by this value. It is
// empty when the changeset log is disabled.
Invocation string `json:"invocation,omitempty"`
// MVCCCommit is the commit handle (see mvcc.CommitHandle) of the MVCC cache of
// the request that builds the payload. On a repository that uses the MVCC
// reference backend, the updates only become visible once that request commits
// its cache, and they are thrown away when the commit fails. The recording hook
// therefore records them only once the cache has committed. It is empty when
// the request has no MVCC cache that it commits, or when the changeset log is
// disabled.
MVCCCommit string `json:"mvcc_commit,omitempty"`
// PolicyGeneration is the generation of the standalone access policy under which a land
// batch admitted its members (policystore.WithAdmissionGeneration). The
// reference-transaction hook refuses the batch's update when the policy in force is another
// one (doc/graft/PLAN12.md, section 5). Only the server builds it from the context, like
// Members.
PolicyGeneration uint64 `json:"policy_generation,omitempty"`
// Members lists the changes that a batched land folded into the updates, in
// the order they were landed (see changelog.WithBatch). The list is capped at
// maxChangelogMembersSize. Only the server builds it from the context, so a
// client cannot set it through the environment of a git command.
Members []changelog.Member `json:"members,omitempty"`
// MembersTruncated is true when Members lacks information: the resolved paths
// were dropped or the list was cut to fit maxChangelogMembersSize.
MembersTruncated bool `json:"members_truncated,omitempty"`
// LandReference and Lands are the identities of the changes that the updates land on
// that branch (see changelog.WithLands and doc/graft/PLAN11.md). They are never cut:
// WithLands bounds them by changelog.MaxLandsSize and refuses a land whose identities
// do not fit. Only the server builds them from the context, like Members.
// LandReference holds the branch name as bytes, which JSON encodes in base64:
// a branch name may hold bytes that are not valid UTF-8, which a JSON string
// would replace.
LandReference []byte `json:"land_reference,omitempty"`
Lands []changelog.Land `json:"lands,omitempty"`
}
// IsZero reports whether m holds no metadata. ChangelogMeta holds slices and
// is therefore not comparable with ==.
func (m ChangelogMeta) IsZero() bool {
return m.Operation == "" &&
m.Actor == "" &&
!m.Agent &&
!m.Rewritten &&
m.Invocation == "" &&
m.MVCCCommit == "" &&
len(m.Members) == 0 &&
!m.MembersTruncated &&
len(m.LandReference) == 0 &&
len(m.Lands) == 0
}
// NewChangelogInvocation returns a new random value for ChangelogMeta.Invocation.
func NewChangelogInvocation() (string, error) {
var invocation [16]byte
if _, err := rand.Read(invocation[:]); err != nil {
return "", fmt.Errorf("generating changelog invocation: %w", err)
}
return hex.EncodeToString(invocation[:]), nil
}
// UserDetails contains all information which is required for hooks
// executed by git-receive-pack, namely the pre-receive, update or post-receive
// hook.
type UserDetails struct {
// Username contains the name of the user who has caused the hook to be executed.
Username string `json:"username"`
// UserID contains the ID of the user who has caused the hook to be executed.
UserID string `json:"userid"`
// Protocol contains the protocol via which the hook was executed. This
// can be one of "web", "ssh" or "smarthttp".
Protocol string `json:"protocol"`
// RemoteIP contains the original IP of the client who initiated the flow leading to this
// target hook.
RemoteIP string `json:"remote_ip"`
}
// jsonHooksPayload wraps the HooksPayload such that we can manually encode the
// repository protobuf message.
type jsonHooksPayload struct {
HooksPayload
Repo string `json:"repository"`
// Changelog carries ChangelogMeta next to the upstream fields. It is not
// restored into HooksPayload on decode, see HooksPayload.Changelog.
Changelog *ChangelogMeta `json:"graft_changelog,omitempty"`
}
// NewHooksPayload creates a new hooks payload which can then be encoded and
// passed to Git hooks.
func NewHooksPayload(
ctx context.Context,
cfg config.Cfg,
repo storage.Repository,
objectHash git.ObjectHash,
tx *txinfo.Transaction,
userDetails *UserDetails,
requestedHooks Hook,
featureFlagsWithValue map[featureflag.FeatureFlag]bool,
) HooksPayload {
flags := make([]FeatureFlagWithValue, 0, len(featureFlagsWithValue))
for flag, enabled := range featureFlagsWithValue {
flags = append(flags, FeatureFlagWithValue{
Flag: flag,
Enabled: enabled,
})
}
// Extract context blob from gRPC metadata
var clientContext []byte
if ctxValue := metadata.GetValue(ctx, metadata.ClientContextMetadataKey); ctxValue != "" {
clientContext = []byte(ctxValue)
}
// The changeset log attributes the update to an operation and an actor.
// Only explicit values are carried here: an operation that cannot be
// derived from the context stays empty, and so does the actor without an
// authenticated identity. The hook that records the update then falls
// back to the request's user ID and to "unknown" (see recordChangesets).
operation := changelog.OperationFromContext(ctx)
if operation == changelog.UnknownOperation {
operation = ""
}
id, hasIdentity := identity.FromContext(ctx)
members, membersTruncated := capChangelogMembers(changelog.BatchFromContext(ctx))
// The payload holds no branch for an update that lands nothing: an empty slice would not
// survive the encoding (omitempty), and the decoded payload would differ.
var landReference []byte
reference, lands := changelog.LandsFromContext(ctx)
if reference != "" {
landReference = []byte(reference)
}
return HooksPayload{
Repo: &gitalypb.Repository{
StorageName: repo.GetStorageName(),
RelativePath: repo.GetRelativePath(),
GitObjectDirectory: repo.GetGitObjectDirectory(),
GitAlternateObjectDirectories: repo.GetGitAlternateObjectDirectories(),
GlRepository: repo.GetGlRepository(),
GlProjectPath: repo.GetGlProjectPath(),
},
ObjectFormat: objectHash.Format,
RuntimeDir: cfg.RuntimeDir,
InternalSocket: cfg.InternalSocketPath(),
InternalSocketToken: cfg.Auth.GetToken(),
Transaction: tx,
UserDetails: userDetails,
RequestedHooks: requestedHooks,
FeatureFlagsWithValue: flags,
GitalyClientContext: clientContext,
StoragePreparing: cfg.Graft.Storage.Mode == "authoritative",
LogFields: log.FromContext(ctx).Data(),
Changelog: ChangelogMeta{
Operation: operation,
Actor: identity.Actor(ctx, ""),
Agent: hasIdentity && id.Source == identity.SourceAgent,
Rewritten: changelog.IsRewritten(ctx),
Members: members,
MembersTruncated: membersTruncated,
LandReference: landReference,
Lands: lands,
MVCCCommit: mvccCommitHandle(ctx, cfg),
PolicyGeneration: policystore.AdmissionGeneration(ctx),
},
}
}
// maxChangelogMembersSize bounds the encoded size of ChangelogMeta.Members. The
// members travel in the environment of every git process of the update, and
// the environment has a limited size.
const maxChangelogMembersSize = 32 << 10
// capChangelogMembers returns the members as they fit into the payload. It drops
// the resolved paths first, and then cuts the list to the longest prefix that
// fits. The truncated result is true when information was dropped. The input is
// not modified.
func capChangelogMembers(members []changelog.Member) ([]changelog.Member, bool) {
if len(members) == 0 {
return nil, false
}
if encodedMembersSize(members) <= maxChangelogMembersSize {
return members, false
}
stripped := make([]changelog.Member, len(members))
for i, m := range members {
m.ResolvedPaths = nil
stripped[i] = m
}
if encodedMembersSize(stripped) <= maxChangelogMembersSize {
return stripped, true
}
// The encoded size grows with every member, so the first prefix that does not
// fit marks where the list is cut.
kept := sort.Search(len(stripped), func(i int) bool {
return encodedMembersSize(stripped[:i+1]) > maxChangelogMembersSize
})
// When even the first member does not fit, which needs an unrealistically large
// actor or object ID, no member is kept. The update then carries no members, so
// the reference-transaction hook does not skip the policy check for it and the
// batch falls back to checking the combined update, which can only deny it.
if kept == 0 {
return nil, true
}
// A truncated list is still safe for the policy skip: every member was checked
// in process for its own actor, and all members of a batch update the same
// branch, so the members that were cut from the payload were checked as well.
return stripped[:kept], true
}
// encodedMembersSize returns the size of the JSON encoding of members. An
// encoding failure counts as too large, so that the members are dropped.
func encodedMembersSize(members []changelog.Member) int {
encoded, err := json.Marshal(members)
if err != nil {
return maxChangelogMembersSize + 1
}
return len(encoded)
}
// mvccCommitHandle returns the handle of the MVCC cache that commits the reference updates
// performed with a hooks payload built from ctx, see ChangelogMeta.MVCCCommit.
func mvccCommitHandle(ctx context.Context, cfg config.Cfg) string {
if cfg.Graft.Changelog.Disabled {
return ""
}
cache := mvcc.CacheFromContext(ctx)
if cache == nil {
return ""
}
return mvcc.CommitHandle(cache)
}
// ChangelogMetaFromEnv returns the changeset log metadata that Env encoded into
// the environment. Without it, the zero value is returned, and the recording
// hook falls back to the request's user ID and to "unknown".
func ChangelogMetaFromEnv(envs []string) (ChangelogMeta, error) {
encoded, ok := lookupEnv(envs, EnvHooksPayload)
if !ok {
return ChangelogMeta{}, ErrPayloadNotFound
}
decoded, err := base64.StdEncoding.DecodeString(encoded)
if err != nil {
return ChangelogMeta{}, err
}
var jsonPayload jsonHooksPayload
if err := json.Unmarshal(decoded, &jsonPayload); err != nil {
return ChangelogMeta{}, err
}
if jsonPayload.Changelog == nil {
return ChangelogMeta{}, nil
}
return *jsonPayload.Changelog, nil
}
func lookupEnv(envs []string, key string) (string, bool) {
for _, env := range envs {
kv := strings.SplitN(env, "=", 2)
if len(kv) != 2 {
continue
}
if kv[0] == key {
return kv[1], true
}
}
return "", false
}
// HooksPayloadFromEnv extracts the HooksPayload from the given environment
// variables. If no HooksPayload exists, it returns a ErrPayloadNotFound
// error.
func HooksPayloadFromEnv(envs []string) (HooksPayload, error) {
encoded, ok := lookupEnv(envs, EnvHooksPayload)
if !ok {
return HooksPayload{}, ErrPayloadNotFound
}
decoded, err := base64.StdEncoding.DecodeString(encoded)
if err != nil {
return HooksPayload{}, err
}
var jsonPayload jsonHooksPayload
if err := json.Unmarshal(decoded, &jsonPayload); err != nil {
return HooksPayload{}, err
}
var repo gitalypb.Repository
err = protojson.Unmarshal([]byte(jsonPayload.Repo), &repo)
if err != nil {
return HooksPayload{}, err
}
payload := jsonPayload.HooksPayload
payload.Repo = &repo
// If no RequestedHooks are passed down to us, then we need to assume
// that the caller of this hook isn't aware of this field and thus just
// pretend that he wants to execute all hooks.
if payload.RequestedHooks == 0 {
payload.RequestedHooks = AllHooks
}
return payload, nil
}
// Env encodes the given HooksPayload into an environment variable.
func (p HooksPayload) Env() (string, error) {
repo, err := protojson.Marshal(p.Repo)
if err != nil {
return "", err
}
jsonPayload := jsonHooksPayload{HooksPayload: p, Repo: string(repo)}
if !p.Changelog.IsZero() {
meta := p.Changelog
jsonPayload.Changelog = &meta
}
marshalled, err := json.Marshal(jsonPayload)
if err != nil {
return "", err
}
encoded := base64.StdEncoding.EncodeToString(marshalled)
return fmt.Sprintf("%s=%s", EnvHooksPayload, encoded), nil
}
// IsHookRequested returns whether the HooksPayload is requesting execution of
// the given git hook.
func (p HooksPayload) IsHookRequested(hook Hook) bool {
return p.RequestedHooks&hook != 0
}