Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/soheilhy/cmux
Connection multiplexer for GoLang: serve different services on the same port!
https://github.com/soheilhy/cmux
Last synced: 10 days ago
JSON representation
Connection multiplexer for GoLang: serve different services on the same port!
- Host: GitHub
- URL: https://github.com/soheilhy/cmux
- Owner: soheilhy
- License: apache-2.0
- Created: 2015-07-29T17:46:44.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2023-12-19T09:16:26.000Z (11 months ago)
- Last Synced: 2024-10-18T15:19:53.751Z (21 days ago)
- Language: Go
- Homepage:
- Size: 103 KB
- Stars: 2,578
- Watchers: 40
- Forks: 198
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- go-awesome - cmux - monitor the same port, start multiple log services (Open source library / The Internet)
- awesome-grpc - cmux - Connection multiplexer for GoLang: serve different services on the same port! Supports gRPC. (Language-Specific / Go)
- awesome - cmux - Connection multiplexer for GoLang: serve different services on the same port! (Go)
- my-awesome - soheilhy/cmux - 12 star:2.6k fork:0.2k Connection multiplexer for GoLang: serve different services on the same port! (Go)
README
# cmux: Connection Mux  [](http://godoc.org/github.com/soheilhy/cmux)
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()
```
Take a look at [other examples in the GoDoc](http://godoc.org/github.com/soheilhy/cmux/#pkg-examples).
## Docs
* [GoDocs](https://godoc.org/github.com/soheilhy/cmux)
## Performance
There is room for improvment but, since we are only matching
the very first bytes of a connection, the performance overheads on
long-lived connections (i.e., RPCs and pipelined HTTP streams)
is negligible.
*TODO(soheil)*: Add benchmarks.
## 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"))
```
# Copyright and License
Copyright 2016 The CMux Authors. All rights reserved.
See [CONTRIBUTORS](https://github.com/soheilhy/cmux/blob/master/CONTRIBUTORS)
for the CMux Authors. Code is released under
[the Apache 2 license](https://github.com/soheilhy/cmux/blob/master/LICENSE).