CMux

https://pkg.go.dev/github.com/soheilhy/cmux
Admin
CMux is a generic Go library for multiplexing network connections based on their payload, allowing...
Tokens:3,413
Snippets:38
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### PrefixMatcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a Matcher that matches a connection if its content starts with any of the provided string prefixes.

```go
func PrefixMatcher(strs ...string) Matcher
```

--------------------------------

### HTTP1HeaderFieldPrefix Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a Matcher that checks if a specific header field in an HTTP/1 request starts with a given prefix.

```go
func HTTP1HeaderFieldPrefix(name, valuePrefix string) Matcher
```

--------------------------------

### HTTP2HeaderFieldPrefix Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a Matcher that checks if a specific header field in an HTTP/2 headers frame starts with a given prefix.

```go
func HTTP2HeaderFieldPrefix(name, valuePrefix string) Matcher
```

--------------------------------

### Multiplexing protocols with cmux

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Demonstrates creating a main listener, initializing a cmux instance, and matching connections to specific protocol servers.

```go
// Create the main listener.
l, err := net.Listen("tcp", ":23456")
if err != nil {
	log.Fatal(err)
}

// Create a cmux.
m := cmux.New(l)

// Match connections in order:
// First grpc, then HTTP, and otherwise Go RPC/TCP.
grpcL := m.Match(cmux.HTTP2HeaderField("content-type", "application/grpc"))
httpL := m.Match(cmux.HTTP1Fast())
trpcL := m.Match(cmux.Any()) // Any means anything that is not yet matched.

// Create your protocol servers.
grpcS := grpc.NewServer()
grpchello.RegisterGreeterServer(grpcS, &server{})

httpS := &http.Server{
	Handler: &helloHTTP1Handler{},
}

trpcS := rpc.NewServer()
trpcS.Register(&ExampleRPCRcvr{})

// Use the muxed listeners for your servers.
go grpcS.Serve(grpcL)
go httpS.Serve(httpL)
go trpcS.Accept(trpcL)

// Start serving!
m.Serve()
```

--------------------------------

### Instantiate New CMux

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Use the New function to create a new CMux instance, passing in the underlying net.Listener to multiplex.

```go
func New(l net.Listener) CMux
```

--------------------------------

### Any Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a Matcher that matches any incoming connection, regardless of its content.

```go
func Any() Matcher
```

--------------------------------

### Connection Multiplexing with CMux

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Demonstrates how to use CMux to multiplex different protocols (gRPC, HTTP, RPC) over a single TCP listener.

```APIDOC
## CMux: Connection Mux

### Description
CMux is a generic Go library to multiplex connections based on their payload. Using CMux, you can serve gRPC, SSH, HTTPS, HTTP, Go RPC, and pretty much any other protocol on the same TCP listener.

### How-To
Simply create your main listener, create a cmux for that listener, and then match connections:

```go
// Create the main listener.
l, err := net.Listen("tcp", ":23456")
if err != nil {
	log.Fatal(err)
}

// Create a cmux.
m := cmux.New(l)

// Match connections in order:
// First grpc, then HTTP, and otherwise Go RPC/TCP.
grpcL := m.Match(cmux.HTTP2HeaderField("content-type", "application/grpc"))
httpL := m.Match(cmux.HTTP1Fast())
trpcL := m.Match(cmux.Any()) // Any means anything that is not yet matched.

// Create your protocol servers.
grpcS := grpc.NewServer()
grpchello.RegisterGreeterServer(grpcS, &server{})

httpS := &http.Server{
	Handler: &helloHTTP1Handler{},
}

trpcS := rpc.NewServer()
trpcS.Register(&ExampleRPCRcvr{})

// Use the muxed listeners for your servers.
go grpcS.Serve(grpcL)
go httpS.Serve(httpL)
go trpcS.Accept(trpcL)

// Start serving!
m.Serve()
```

### Limitations
*   **TLS**: `net/http` uses a type assertion to identify TLS connections; since cmux's lookahead-implementing connection wraps the underlying TLS connection, this type assertion fails. Because of that, you can serve HTTPS using cmux but `http.Request.TLS` would not be set in your handlers.
*   **Different Protocols on The Same Connection**: `cmux` matches the connection when it's accepted. For example, one connection can be either gRPC or REST, but not both. That is, we assume that a client connection is either used for gRPC or REST.
*   **Java gRPC Clients**: Java gRPC client blocks until it receives a SETTINGS frame from the server. If you are using the Java client to connect to a cmux'ed gRPC server please match with writers:

```go
grpcl := m.MatchWithWriters(cmux.HTTP2MatchHeaderFieldSendSettings("content-type", "application/grpc"))
```
```

--------------------------------

### func New

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Instantiates a new connection multiplexer for a given network listener.

```APIDOC
## func New

### Description
Instantiates a new connection multiplexer.

### Parameters
#### Request Body
- **l** (net.Listener) - Required - The network listener to multiplex.
```

--------------------------------

### CMux Interface Methods

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Core methods for managing connection matching and server lifecycle.

```APIDOC
## CMux Interface

### Methods
- **Match(...Matcher) net.Listener**: Returns a listener that accepts connections matched by at least one matcher.
- **MatchWithWriters(...MatchWriter) net.Listener**: Returns a listener that accepts connections matched by at least one matcher writer.
- **Serve() error**: Starts multiplexing the listener. Blocks execution.
- **Close()**: Closes the cmux server and stops accepting connections.
- **HandleError(ErrorHandler)**: Registers an error handler for listener errors.
- **SetReadTimeout(time.Duration)**: Sets a timeout for the read of matchers.
```

--------------------------------

### HTTP2 Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a Matcher that identifies HTTP/2 connections by inspecting the frame header of the first frame.

```go
func HTTP2() Matcher
```

--------------------------------

### HTTP1 Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a Matcher that attempts to identify HTTP/1 requests by parsing the first line or up to 4096 bytes of the connection.

```go
func HTTP1() Matcher
```

--------------------------------

### Matching gRPC connections for Java clients

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Use MatchWithWriters when connecting with Java gRPC clients to ensure the server sends necessary SETTINGS frames.

```go
grpcl := m.MatchWithWriters(cmux.HTTP2MatchHeaderFieldSendSettings("content-type", "application/grpc"))
```

--------------------------------

### CMux Matchers

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Available matchers for identifying and routing network connections.

```APIDOC
### Matcher Functions

- `cmux.Any()`: Matches any connection not yet matched.
- `cmux.HTTP1()`: Matches HTTP/1.x connections.
- `cmux.HTTP1Fast(extMethods ...string)`: Matches HTTP/1.x connections, optionally accepting extended methods.
- `cmux.HTTP1HeaderField(name, value string)`: Matches HTTP/1.x connections based on a specific header field and value.
- `cmux.HTTP1HeaderFieldPrefix(name, valuePrefix string)`: Matches HTTP/1.x connections based on a header field with a prefix value.
- `cmux.HTTP2()`: Matches HTTP/2 connections.
- `cmux.HTTP2HeaderField(name, value string)`: Matches HTTP/2 connections based on a specific header field and value.
- `cmux.HTTP2HeaderFieldPrefix(name, valuePrefix string)`: Matches HTTP/2 connections based on a header field with a prefix value.
- `cmux.PrefixMatcher(strs ...string)`: Matches connections based on a prefix of the payload.
- `cmux.TLS(versions ...int)`: Matches TLS connections, optionally specifying TLS versions.
```

--------------------------------

### HTTP2MatchHeaderFieldPrefixSendSettings Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a MatchWriter that matches a header field by prefix and sends HTTP/2 settings. Prefer HTTP2HeaderFieldPrefix if the client doesn't block on SETTINGS frames.

```go
func HTTP2MatchHeaderFieldPrefixSendSettings(name, valuePrefix string) MatchWriter
```

--------------------------------

### HTTP1Fast Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates an optimistic Matcher for HTTP/1 requests that only checks request methods. It's faster but less accurate than HTTP1.

```go
func HTTP1Fast(extMethods ...string) Matcher
```

--------------------------------

### Matcher Functions

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Available matcher functions to identify connection protocols.

```APIDOC
## Matcher Functions

- **Any()**: Matches any connection.
- **HTTP1()**: Matches HTTP 1 connections.
- **HTTP1Fast(...string)**: Optimistically matches HTTP methods.
- **HTTP1HeaderField(name, value)**: Matches HTTP 1 header fields.
- **HTTP1HeaderFieldPrefix(name, valuePrefix)**: Matches HTTP 1 header field prefixes.
- **HTTP2()**: Matches HTTP 2 connections.
- **HTTP2HeaderField(name, value)**: Matches HTTP 2 header fields.
- **HTTP2HeaderFieldPrefix(name, valuePrefix)**: Matches HTTP 2 header field prefixes.
- **PrefixMatcher(...string)**: Matches connections starting with specific strings.
```

--------------------------------

### CMux Match Writers

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Custom match writers for advanced connection matching, particularly for protocols like gRPC.

```APIDOC
### MatchWriter Functions

- `cmux.HTTP2MatchHeaderFieldPrefixSendSettings(name, valuePrefix string)`: Creates a MatchWriter for HTTP/2 that matches when a header field with a prefix value is sent in the initial SETTINGS frame.
- `cmux.HTTP2MatchHeaderFieldSendSettings(name, value string)`: Creates a MatchWriter for HTTP/2 that matches when a specific header field and value are sent in the initial SETTINGS frame.
```

--------------------------------

### Match TLS connections

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Matches HTTPS requests, optionally restricted to a specific whitelist of TLS versions.

```go
func TLS(versions ...int) Matcher
```

```go
TLS(tls.VersionTLS11, tls.VersionTLS12)
```

--------------------------------

### HTTP2MatchHeaderFieldSendSettings Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a MatchWriter that matches an exact header field and sends HTTP/2 settings. Prefer HTTP2HeaderField if the client doesn't block on SETTINGS frames.

```go
func HTTP2MatchHeaderFieldSendSettings(name, value string) MatchWriter
```

--------------------------------

### MuxConn structure definition

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Wraps a net.Conn to provide transparent sniffing of connection data.

```go
type MuxConn struct {
	net.Conn
	// contains filtered or unexported fields
}
```

--------------------------------

### HTTP1HeaderField Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a Matcher that checks for a specific header field and value in the first request of an HTTP/1 connection.

```go
func HTTP1HeaderField(name, value string) Matcher
```

--------------------------------

### Error variables for listener and server states

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Standard error variables used to indicate the state of the underlying listener or mux server.

```go
var ErrListenerClosed = errListenerClosed("mux: listener closed")
```

```go
var ErrServerClosed = errors.New("mux: server closed")
```

--------------------------------

### Read from MuxConn

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Reads data from the underlying connection, following standard io.Reader behavior regarding EOF and error handling.

```go
func (m *MuxConn) Read(p []byte) (int, error)
```

--------------------------------

### HTTP2HeaderField Matcher

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Creates a Matcher that checks for a specific header field and value in the first headers frame of an HTTP/2 connection.

```go
func HTTP2HeaderField(name, value string) Matcher
```

--------------------------------

### type MuxConn

Source: https://pkg.go.dev/github.com/soheilhy/cmux

A wrapper for net.Conn that provides transparent sniffing of connection data.

```APIDOC
## type MuxConn

### Description
MuxConn wraps a net.Conn and provides transparent sniffing of connection data.

### Methods
- **Read(p []byte) (int, error)**: Reads data from the connection, following standard io.Reader behavior regarding errors and EOF.
```

--------------------------------

### Implement net.Error for ErrNotMatched

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Provides methods to satisfy the net.Error interface for ErrNotMatched, indicating if the error is temporary or a timeout.

```go
func (e ErrNotMatched) Error() string
```

```go
func (e ErrNotMatched) Temporary() bool
```

```go
func (e ErrNotMatched) Timeout() bool
```

--------------------------------

### func TLS

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Matches HTTPS requests with optional TLS version filtering.

```APIDOC
## func TLS

### Description
Matches HTTPS requests. By default, any TLS handshake packet is matched. An optional whitelist of versions can be passed in to restrict the matcher.

### Parameters
- **versions** (...int) - Optional - A whitelist of TLS versions to restrict the matcher (e.g., tls.VersionTLS11, tls.VersionTLS12).
```

--------------------------------

### Define CMux Interface

Source: https://pkg.go.dev/github.com/soheilhy/cmux

The CMux interface defines the core methods for managing a network connection multiplexer, including matching connections, serving traffic, and handling errors.

```go
type CMux interface {
	// Match returns a net.Listener that sees (i.e., accepts) only
	// the connections matched by at least one of the matcher.
	//
	// The order used to call Match determines the priority of matchers.
	Match(...Matcher) net.Listener
	// MatchWithWriters returns a net.Listener that accepts only the
	// connections that matched by at least of the matcher writers.
	//
	// Prefer Matchers over MatchWriters, since the latter can write on the
	// connection before the actual handler.
	//
	// The order used to call Match determines the priority of matchers.
	MatchWithWriters(...MatchWriter) net.Listener
	// Serve starts multiplexing the listener. Serve blocks and perhaps
	// should be invoked concurrently within a go routine.
	Serve() error
	// Closes cmux server and stops accepting any connections on listener
	Close()
	// HandleError registers an error handler that handles listener errors.
	HandleError(ErrorHandler)
	// sets a timeout for the read of matchers
	SetReadTimeout(time.Duration)
}
```

--------------------------------

### Define Matcher Type

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Matcher is a function type that determines if a connection's content matches a specific criteria.

```go
type Matcher func(io.Reader) bool
```

--------------------------------

### CMux Errors

Source: https://pkg.go.dev/github.com/soheilhy/cmux

Error types and their meanings within the CMux library.

```APIDOC
### Error Types

- `var ErrListenerClosed`: Returned from `muxListener.Accept` when the underlying listener is closed.
- `var ErrServerClosed`: Returned from `muxListener.Accept` when the mux server is closed.
- `type ErrNotMatched`: Represents a connection that could not be matched to any protocol.
    - `Error() string`: Returns the error message.
    - `Temporary() bool`: Indicates if the error is temporary.
    - `Timeout() bool`: Indicates if the error is a timeout.
```

--------------------------------

### Define MatchWriter Type

Source: https://pkg.go.dev/github.com/soheilhy/cmux

MatchWriter is a function type that matches a connection and can optionally write data, such as for performing a handshake.

```go
type MatchWriter func(io.Writer, io.Reader) bool
```

--------------------------------

### Define ErrorHandler Type

Source: https://pkg.go.dev/github.com/soheilhy/cmux

ErrorHandler is a function type that handles errors encountered by the CMux. It returns a boolean indicating whether the multiplexer should continue serving.

```go
type ErrorHandler func(error) bool
```

--------------------------------

### ErrNotMatched Struct Definition

Source: https://pkg.go.dev/github.com/soheilhy/cmux

ErrNotMatched is an error type returned when a connection does not match any registered multiplexer rules.

```go
type ErrNotMatched struct {
	// contains filtered or unexported fields
}
```
Tokens:
Raw