Git designed for AI agents.
package stats
import (
"bytes"
"context"
"encoding/binary"
"errors"
"fmt"
"io"
"strings"
"github.com/feder-cr/git-ai/internal/git/pktline"
"github.com/feder-cr/git-ai/internal/helper/text"
"github.com/feder-cr/git-ai/internal/log"
"github.com/prometheus/client_golang/prometheus"
)
// ReceivePackStatsPrefixSize is the number of leading bytes of a
// git-receive-pack request that are captured to extract push statistics. The
// command list and the packfile header sit at the very start of the request.
// A push whose command list is larger than this loses its statistics.
const ReceivePackStatsPrefixSize = 64 * 1024
// ReceivePack parses the request a Git client sends to git-receive-pack(1)
// (i.e. the client side of a push). The request consists of a list of
// reference-update commands in pkt-line format, terminated by a flush packet,
// optionally followed by a packfile.
//
// See https://git-scm.com/docs/pack-protocol#_reference_update_request_and_packfile_transfer.
type ReceivePack struct {
// UserAgent is the user agent announced by the client, e.g. "git/2.53.0".
UserAgent string
// Capabilities announced by the client (report-status, side-band-64k, ...).
Caps []string
// Commands is the number of reference-update commands in the request.
Commands int
// Creates is the number of references the client wants to create.
Creates int
// Deletes is the number of references the client wants to delete.
Deletes int
// Updates is the number of references the client wants to update.
Updates int
// Objects is the number of objects in the packfile as announced by the
// PACK header. A delete-only push carries no packfile
// and leaves this at zero.
Objects uint32
// Packets is the total number of pktlines in the command list. It
// distinguishes an empty request from one whose command list was
// truncated.
Packets int
}
// ParseReceivePack parses a git-receive-pack(1) request from the given reader.
func ParseReceivePack(body io.Reader) (ReceivePack, error) {
r := ReceivePack{}
return r, r.Parse(body)
}
// Parse reads the reference-update commands and the packfile header from a
// git-receive-pack(1) request body.
func (r *ReceivePack) Parse(body io.Reader) error {
capsParsed := false
inPushCert := false
sawFlush := false
for {
// Use pktline.Read rather than pktline.NewScanner because we should
// strictly consume up to the end of the command-list in the Reference
// Update Request.
pkt, err := pktline.Read(body)
if err != nil {
if errors.Is(err, io.EOF) {
break
}
return fmt.Errorf("reading command list: %w", err)
}
if pktline.IsFlush(pkt) {
sawFlush = true
break
}
r.Packets++
line := text.ChompBytes(pktline.Data(pkt))
// A push certificate (git push --signed) wraps the command list
// together with header and PGP-signature lines. Skip the whole block
// rather than miscount its contents as reference updates.
if inPushCert {
if strings.HasPrefix(line, "push-cert-end") {
inPushCert = false
}
continue
}
if strings.HasPrefix(line, "push-cert") {
inPushCert = true
continue
}
// Shallow lines precede the command list.
if strings.HasPrefix(line, "shallow ") {
continue
}
// The first command line carries the capabilities after a NUL byte:
// <old-oid> SP <new-oid> SP <ref-name> NUL <capabilities>
if !capsParsed {
capsParsed = true
if idx := strings.IndexByte(line, 0); idx >= 0 {
r.Caps = strings.Fields(line[idx+1:])
for _, cap := range r.Caps {
if agent, ok := strings.CutPrefix(cap, "agent="); ok {
r.UserAgent = agent
break
}
}
line = line[:idx]
}
}
fields := strings.SplitN(line, " ", 3)
if len(fields) != 3 {
continue
}
oldOID, newOID := fields[0], fields[1]
r.Commands++
switch {
case isZeroOID(oldOID):
r.Creates++
case isZeroOID(newOID):
r.Deletes++
default:
r.Updates++
}
}
if !sawFlush {
// An empty stream happens when the RPC fails before git-receive-pack
// reads its input.
if r.Packets == 0 {
return nil
}
return fmt.Errorf("incomplete command list: no flush after %d packets", r.Packets)
}
// The packfile header is "PACK" + 4-byte version + 4-byte object count,
// all big-endian. EOF means no packfile follows the command list.
var header [12]byte
if _, err := io.ReadFull(body, header[:]); err != nil {
if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) {
return nil
}
return fmt.Errorf("reading packfile header: %w", err)
}
if string(header[0:4]) != "PACK" {
return fmt.Errorf("unexpected packfile signature: %q", header[0:4])
}
r.Objects = binary.BigEndian.Uint32(header[8:12])
return nil
}
func isZeroOID(oid string) bool {
for _, c := range oid {
if c != '0' {
return false
}
}
return len(oid) > 0
}
// UpdateMetrics observes the push's object count in the given histogram. The
// histogram deliberately carries no labels: repository and user attribution
// stays in the logs to keep metric cardinality bounded.
func (r *ReceivePack) UpdateMetrics(objects prometheus.Histogram) {
objects.Observe(float64(r.Objects))
}
// UpdateLogFields records the push statistics as custom log fields on the
// request.
func (r *ReceivePack) UpdateLogFields(ctx context.Context) {
customFields := log.CustomFieldsFromContext(ctx)
if customFields == nil {
return
}
if r.UserAgent != "" {
customFields.RecordMetadata("receive_pack.user_agent", r.UserAgent)
}
customFields.RecordMetadata("receive_pack.commands", r.Commands)
customFields.RecordMetadata("receive_pack.creates", r.Creates)
customFields.RecordMetadata("receive_pack.deletes", r.Deletes)
customFields.RecordMetadata("receive_pack.updates", r.Updates)
customFields.RecordMetadata("receive_pack.objects", int(r.Objects))
log.FromContext(ctx).
WithFields(customFields.Fields()).
InfoContext(ctx, "receive-pack request parsed")
}
// PrefixCapture is an io.Writer that retains the first ReceivePackStatsPrefixSize
// bytes written to it and discards the rest. It never blocks or errors, so it
// can tee the git-receive-pack stdin path without affecting git.
type PrefixCapture struct {
buf []byte
}
// Write retains bytes up to the prefix limit and reports the full length as
// written so the writer never short-writes.
func (c *PrefixCapture) Write(p []byte) (int, error) {
if room := ReceivePackStatsPrefixSize - len(c.buf); room > 0 {
c.buf = append(c.buf, p[:min(room, len(p))]...)
}
return len(p), nil
}
// Bytes returns the captured prefix.
func (c *PrefixCapture) Bytes() []byte {
return c.buf
}
// RecordReceivePack parses a captured prefix of a git-receive-pack request
// and, when it holds a complete command list, records push statistics as log
// fields and observes the object count in the histogram.
func RecordReceivePack(ctx context.Context, logger log.Logger, prefix []byte, objects prometheus.Histogram) {
var rp ReceivePack
if err := rp.Parse(bytes.NewReader(prefix)); err != nil {
logger.WithError(err).DebugContext(ctx, "failed parsing receive-pack request")
return
}
// No packets at all means the RPC failed before git read its input. A
// signed push reports zero commands but still carries packets and an
// object count, so don't guard on Commands here.
if rp.Packets == 0 {
return
}
rp.UpdateLogFields(ctx)
rp.UpdateMetrics(objects)
}