pktline

Documentation

Overview

Package pktline implements utility functions for working with the Git pkt-line format. See https://git-scm.com/docs/protocol-common#_pkt_line_format

Index

• Constants
• func Data(pkt []byte) []byte
• func EachSidebandPacket(r io.Reader, fn func(byte, []byte) error) error
• func IsFlush(pkt []byte) bool
• func NewScanner(r io.Reader) *bufio.Scanner
• func Payload(pkt []byte) ([]byte, error)
• func PktDelim() []byte
• func PktDone() []byte
• func PktFlush() []byte
• func WriteDelim(w io.Writer) error
• func WriteFlush(w io.Writer) error
• func WriteString(w io.Writer, str string) (int, error)
• type ReadMonitor
  • func NewReadMonitor(ctx context.Context, r io.Reader) (*os.File, *ReadMonitor, func(), error)
  • func (m *ReadMonitor) Monitor(ctx context.Context, pkt []byte, timeout helper.Ticker, cancelFn func())
• type SidebandWriter
  • func NewSidebandWriter(w io.Writer) *SidebandWriter
  • func (sw *SidebandWriter) Writer(band byte) io.Writer

Constants

const (
	// MaxSidebandData is the maximum number of bytes that fits into one Git
	// pktline side-band-64k packet.
	MaxSidebandData = MaxPktSize - 5

	// MaxPktSize is the maximum size of content of a Git pktline side-band-64k
	// packet, including size of length and band number
	// https://gitlab.com/gitlab-org/git/-/blob/v2.30.0/pkt-line.h#L216
	MaxPktSize = 65520
)

Functions

func Data

func Data(pkt []byte) []byte

Data returns the packet pkt without its length header. The length header is not validated. Returns an empty slice when pkt is a magic packet such as '0000'.

func EachSidebandPacket

func EachSidebandPacket(r io.Reader, fn func(byte, []byte) error) error

EachSidebandPacket iterates over a side-band-64k pktline stream. For each packet, it will call fn with the band ID and the packet. Fn must not retain the packet.

func IsFlush

func IsFlush(pkt []byte) bool

IsFlush detects the special flush packet '0000'

func NewScanner

func NewScanner(r io.Reader) *bufio.Scanner

NewScanner returns a bufio.Scanner that splits on Git pktline boundaries

func Payload

func Payload(pkt []byte) ([]byte, error)

Payload returns the pktline's data. It verifies that the length header matches what we expect as data.

func PktDelim

func PktDelim() []byte

PktDelim returns the bytes for a "delim" packet.

func PktDone

func PktDone() []byte

PktDone returns the bytes for a "done" packet.

func PktFlush

func PktFlush() []byte

PktFlush returns the bytes for a "flush" packet.

func WriteDelim

func WriteDelim(w io.Writer) error

WriteDelim writes a pkt delim packet.

func WriteFlush

func WriteFlush(w io.Writer) error

WriteFlush writes a pkt flush packet.

func WriteString

func WriteString(w io.Writer, str string) (int, error)

WriteString writes a string with pkt-line framing

Types

type ReadMonitor

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

ReadMonitor monitors an io.Reader, waiting for a specified packet. If the packet doesn't come within a timeout, a cancel function is called. This can be used to place a timeout on the *negotiation* phase of some git commands, aborting them if it is exceeded.

This timeout prevents a class of "use-after-check" security issue when the access check for a git command is run before the command itself. The user has control of stdin for the git command, and if they can delay input for an arbitrarily long time, they can gain access days or weeks after the access check has completed.

This approach is better than placing a timeout on the overall git operation because there is a conflict between mitigating the use-after-check with a short timeout, and allowing long-lived git operations to complete. The negotiation phase is a small proportion of the time taken for a large git fetch, for instance, so tighter limits can be placed on it, leading to a better mitigation.

func NewReadMonitor

func NewReadMonitor(ctx context.Context, r io.Reader) (*os.File, *ReadMonitor, func(), error)

NewReadMonitor wraps the provided reader with an os.Pipe(), returning the read end for onward use.

Call Monitor(pkt, timeout, cancelFn) to start streaming from the reader to to the pipe. The stream will be monitored for a pktline-formatted packet matching pkt. If it isn't seen within the timeout, cancelFn will be called.

The returned function will release allocated resources. You must make sure to call this function.

func (*ReadMonitor) Monitor

func (m *ReadMonitor) Monitor(ctx context.Context, pkt []byte, timeout helper.Ticker, cancelFn func())

Monitor should be called at most once. It scans the stream, looking for the specified packet, and will call cancelFn if it isn't seen within the timeout

type SidebandWriter

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

SidebandWriter multiplexes byte streams into a single side-band-64k stream.

func NewSidebandWriter

func NewSidebandWriter(w io.Writer) *SidebandWriter

NewSidebandWriter instantiates a new SidebandWriter.

func (*SidebandWriter) Writer

func (sw *SidebandWriter) Writer(band byte) io.Writer

Writer returns an io.Writer that writes into the multiplexed stream. Writers for different bands can be used concurrently.