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
• type Channel
  • func Line(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
• type Framing
  • func Header(mimeType string) 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

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. The methods of a Channel need not be safe for concurrent use.

func Line

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

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.

func Pipe

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

Pipe creates a pair of connected in-memory channels using the specified framing discipline. 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.

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

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.