channel

Documentation

Overview

Package channel defines a communications channel that can encode/transmit and decode/receive data records with a configurable framing discipline, and provides some simple framing implementations.

Index

• Variables
• func IsErrClosing(err error) bool
• type Channel
  • func Decimal(r io.Reader, wc io.WriteCloser) Channel
  • func Pipe(framing Framing) (client, server Channel)
  • func RawJSON(r io.Reader, wc io.WriteCloser) Channel
  • func Varint(r io.Reader, wc io.WriteCloser) Channel
  • func WithTrigger(ch Channel, trigger func()) Channel
• type Framing
  • func Header(mimeType string) Framing
  • func Split(b byte) Framing
• type Receiver
• type Sender

Variables

var JSON = Header("application/json")

JSON is a header framing with content type application/json.

var LSP = Header("application/vscode-jsonrpc; charset=utf-8")

LSP is a framing that transmits and receives messages on r and wc using the Language Server Protocol (LSP) framing, defined by the LSP specification at https://microsoft.github.io/language-server-protocol

var Line = Split('\n')

Line is a framing that transmits and receives messages on r and wc with line framing. Each message is terminated by a Unicode LF (10). This framing has the constraint that outbound records may not contain any LF characters.

Functions

func IsErrClosing

func IsErrClosing(err error) bool

IsErrClosing reports whether err is the internal error returned by a read from a pipe or socket that is closed. This is false for err == nil.

Types

type Channel

type Channel interface {
	Sender
	Receiver

	// Close shuts down the channel, after which no further records may be
	// sent or received.
	Close() error
}

A Channel represents the ability to transmit and receive data records. A channel does not interpret the contents of a record, but may add and remove framing so that records can be embedded in higher-level protocols.

One sender and one receiver may use a Channel concurrently, but the methods of a Channel are not otherwise required to be safe for concurrent use.

func Decimal

func Decimal(r io.Reader, wc io.WriteCloser) Channel

Decimal is a framing that transmits and receives messages on r and wc, with each message prefixed by its length encoded as a line of decimal digits.

For example, the message "empanada\n" is encoded as:

9\n
empanada\n

func Pipe

func Pipe(framing Framing) (client, server Channel)

Pipe creates a pair of connected in-memory channels using the specified framing discipline. Sends to client will be received by server, and vice versa. Pipe will panic if framing == nil.

func RawJSON

func RawJSON(r io.Reader, wc io.WriteCloser) Channel

RawJSON is a framing that transmits and receives records on r and wc, in which each record is defined by being a complete JSON value. No padding or other separation is added.

func Varint

func Varint(r io.Reader, wc io.WriteCloser) Channel

Varint is a framing that transmits and receives messages on r and wc, with each message prefixed by its length encoded in a varint as defined by the encoding/binary package.

func WithTrigger

func WithTrigger(ch Channel, trigger func()) Channel

WithTrigger returns a Channel that delegates I/O operations to ch, and when a receive operation returns io.EOF it calls the trigger.

type Framing

type Framing func(io.Reader, io.WriteCloser) Channel

A Framing converts a reader and a writer into a Channel with a particular message-framing discipline.

func Header

func Header(mimeType string) Framing

Header defines a framing that transmits and receives messages using a header prefix similar to HTTP, in which the value of the string is used to describe the content encoding.

Specifically, each message is sent in the format:

Content-Type: <mime-type>\r\n
Content-Length: <nbytes>\r\n
\r\n
<payload>

The length (nbytes) is encoded as decimal digits. For example, given a ContentType value "application/json", the message "123\n" is transmitted as:

Content-Type: application/json\r\n
Content-Length: 4\r\n
\r\n
123\n

If mimeType == "", the Content-Type header is omitted.

func Split

func Split(b byte) Framing

Split returns a framing in which each message is terminated by the specified byte value. The framing has the constraint that outbound records may not contain the split byte internally.

type Receiver

type Receiver interface {
	// Recv returns the next available record from the channel.  If no further
	// messages are available, it returns io.EOF.  Each call to Recv fetches a
	// single complete record.
	Recv() ([]byte, error)
}

A Receiver represents the ability to receive a message from a channel.

type Sender

type Sender interface {
	// Send transmits a record on the channel. Each call to Send transmits one
	// complete record.
	Send([]byte) error
}

A Sender represents the ability to transmit a message on a channel.