pktline

README

Git pkt-line Toolkit

This package is a Go language toolkit for reading and writing files using the Git pkt-line format used in various Git operations.

Documentation

Index

• Constants
• type Pktline
  • func NewPktline(r io.Reader, w io.Writer) *Pktline
  • func (p *Pktline) ReadPacket() ([]byte, error)
  • func (p *Pktline) ReadPacketList() ([]string, error)
  • func (p *Pktline) ReadPacketText() (string, error)
  • func (p *Pktline) ReadPacketTextWithLength() (string, int, error)
  • func (p *Pktline) ReadPacketWithLength() ([]byte, int, error)
  • func (p *Pktline) WriteDelim() error
  • func (p *Pktline) WriteFlush() error
  • func (p *Pktline) WritePacket(data []byte) error
  • func (p *Pktline) WritePacketList(list []string) error
  • func (p *Pktline) WritePacketText(data string) error
• type PktlineReader
  • func NewPktlineReader(r io.Reader, c int) *PktlineReader
  • func NewPktlineReaderFromPktline(pl *Pktline, c int) *PktlineReader
  • func (r *PktlineReader) Read(p []byte) (int, error)
  • func (r *PktlineReader) Reset()
• type PktlineWriter
  • func NewPktlineWriter(w io.Writer, c int) *PktlineWriter
  • func NewPktlineWriterFromPktline(pl *Pktline, c int) *PktlineWriter
  • func (w *PktlineWriter) Flush() error
  • func (w *PktlineWriter) Write(p []byte) (int, error)

Constants

const (
	// MaxPacketLength is the maximum total (header+payload) length
	// encode-able within one packet using Git's pkt-line protocol.
	MaxPacketLength = 65516
)

Types

type Pktline

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

func NewPktline

func NewPktline(r io.Reader, w io.Writer) *Pktline

func (*Pktline) ReadPacket

func (p *Pktline) ReadPacket() ([]byte, error)

ReadPacket reads a single packet entirely and returns the data encoded within it. Errors can occur in several cases, as described below.

1. If no data was present in the reader, and no more data could be read (the pipe was closed, etc) than an io.EOF will be returned.
2. If there was some data to be read, but the pipe or reader was closed before an entire packet (or header) could be ingested, an io.ErrShortBuffer error will be returned.
3. If there was a valid header, but no body associated with the packet, an "Invalid packet length." error will be returned.
4. If the data in the header could not be parsed as a hexadecimal length in the Git Pktline format, the parse error will be returned.

If none of the above cases fit the state of the data on the wire, the packet is returned along with a nil error.

func (*Pktline) ReadPacketList

func (p *Pktline) ReadPacketList() ([]string, error)

ReadPacketList reads as many packets as possible using the `readPacketText` function before encountering a flush packet. It returns a slice of all the packets it read, or an error if one was encountered.

func (*Pktline) ReadPacketText

func (p *Pktline) ReadPacketText() (string, error)

ReadPacketText follows identical semantics to the `readPacket()` function, but additionally removes the trailing `\n` LF from the end of the packet, if present.

func (*Pktline) ReadPacketTextWithLength

func (p *Pktline) ReadPacketTextWithLength() (string, int, error)

ReadPacketTextWithLength follows identical semantics to the `ReadPacketWithLength()` function, but additionally removes the trailing `\n` LF from the end of the packet, if present. The length field is not modified.

func (*Pktline) ReadPacketWithLength

func (p *Pktline) ReadPacketWithLength() ([]byte, int, error)

ReadPacketWithLength is exactly like ReadPacket, but on success, it also returns the packet length header value. This is useful to distinguish between flush and delim packets, which will return 0 and 1 respectively. For data packets, the length will be four more than the number of bytes in the slice.

func (*Pktline) WriteDelim

func (p *Pktline) WriteDelim() error

WriteDelim writes the separating "delim" packet and then flushes the underlying buffered writer.

If any error was encountered along the way, it will be returned immediately

func (*Pktline) WriteFlush

func (p *Pktline) WriteFlush() error

WriteFlush writes the terminating "flush" packet and then flushes the underlying buffered writer.

If any error was encountered along the way, it will be returned immediately

func (*Pktline) WritePacket

func (p *Pktline) WritePacket(data []byte) error

WritePacket writes the given data in "data" to the underlying data stream using Git's `pkt-line` format.

If the data was longer than MaxPacketLength, an error will be returned. If there was any error encountered while writing any component of the packet (hdr, payload), it will be returned.

NB: writePacket does _not_ flush the underlying buffered writer. See instead: `writeFlush()`.

func (*Pktline) WritePacketList

func (p *Pktline) WritePacketList(list []string) error

WritePacketList writes a slice of strings using the semantics of and then writes a terminating flush sequence afterwords.

If any error was encountered, it will be returned immediately.

func (*Pktline) WritePacketText

func (p *Pktline) WritePacketText(data string) error

WritePacketText follows the same semantics as `writePacket`, but appends a trailing "\n" LF character to the end of the data.

type PktlineReader

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

func NewPktlineReader

func NewPktlineReader(r io.Reader, c int) *PktlineReader

NewPktlineReader returns a new *PktlineReader, which will read from the underlying data stream "r". The internal buffer is initialized with the given capacity, "c".

If "r" is already a `*PktlineReader`, it will be returned as-is.

func NewPktlineReaderFromPktline

func NewPktlineReaderFromPktline(pl *Pktline, c int) *PktlineReader

NewPktlineReaderFromPktline returns a new *PktlineReader based on the underlying *Pktline object. The internal buffer is initialized with the given capacity, "c".

func (*PktlineReader) Read

func (r *PktlineReader) Read(p []byte) (int, error)

func (*PktlineReader) Reset

func (r *PktlineReader) Reset()

Reset causes the reader to reset the end-of-file indicator and continue reading packets from the underlying reader.

type PktlineWriter

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

PktlineWriter is an implementation of `io.Writer` which writes data buffers "p" to an underlying pkt-line stream for use with the Git pkt-line format.

func NewPktlineWriter

func NewPktlineWriter(w io.Writer, c int) *PktlineWriter

NewPktlineWriter returns a new *PktlineWriter, which will write to the underlying data stream "w". The internal buffer is initialized with the given capacity, "c".

If "w" is already a `*PktlineWriter`, it will be returned as-is.

func NewPktlineWriterFromPktline

func NewPktlineWriterFromPktline(pl *Pktline, c int) *PktlineWriter

NewPktlineWriterFromPktline returns a new *PktlineWriter based on the underlying *Pktline object. The internal buffer is initialized with the given capacity, "c".

func (*PktlineWriter) Flush

func (w *PktlineWriter) Flush() error

Flush empties the internal buffer used to store data temporarily and then writes the pkt-line's FLUSH packet, to signal that it is done writing this chunk of data.

func (*PktlineWriter) Write

func (w *PktlineWriter) Write(p []byte) (int, error)

Write implements the io.Writer interface's `Write` method by providing a packet-based backend to the given buffer "p".

As many bytes are removed from "p" as possible and stored in an internal buffer until the amount of data in the internal buffer is enough to write a single packet. Once the internal buffer is full, a packet is written to the underlying stream of data, and the process repeats.

When the caller has no more data to write in the given chunk of packets, a subsequent call to `Flush()` SHOULD be made in order to signify that the current pkt sequence has terminated, and a new one can begin.

Write returns the number of bytes in "p" accepted into the writer, which _MAY_ be written to the underlying protocol stream, or may be written into the internal buffer.

If any error was encountered while either buffering or writing, that error is returned, along with the number of bytes written to the underlying protocol stream, as described above.