1# cmux: Connection Mux  [](http://godoc.org/github.com/soheilhy/cmux)
2
3cmux is a generic Go library to multiplex connections based on
4their payload. Using cmux, you can serve gRPC, SSH, HTTPS, HTTP,
5Go RPC, and pretty much any other protocol on the same TCP listener.
6
7## How-To
8Simply create your main listener, create a cmux for that listener,
9and then match connections:
10```go
11// Create the main listener.
12l, err := net.Listen("tcp", ":23456")
13if err != nil {
14 log.Fatal(err)
15}
16
17// Create a cmux.
18m := cmux.New(l)
19
20// Match connections in order:
21// First grpc, then HTTP, and otherwise Go RPC/TCP.
22grpcL := m.Match(cmux.HTTP2HeaderField("content-type", "application/grpc"))
23httpL := m.Match(cmux.HTTP1Fast())
24trpcL := m.Match(cmux.Any()) // Any means anything that is not yet matched.
25
26// Create your protocol servers.
27grpcS := grpc.NewServer()
28grpchello.RegisterGreeterServer(grpcS, &server{})
29
30httpS := &http.Server{
31 Handler: &helloHTTP1Handler{},
32}
33
34trpcS := rpc.NewServer()
35trpcS.Register(&ExampleRPCRcvr{})
36
37// Use the muxed listeners for your servers.
38go grpcS.Serve(grpcL)
39go httpS.Serve(httpL)
40go trpcS.Accept(trpcL)
41
42// Start serving!
43m.Serve()
44```
45
46Take a look at [other examples in the GoDoc](http://godoc.org/github.com/soheilhy/cmux/#pkg-examples).
47
48## Docs
49* [GoDocs](https://godoc.org/github.com/soheilhy/cmux)
50
51## Performance
52There is room for improvment but, since we are only matching
53the very first bytes of a connection, the performance overheads on
54long-lived connections (i.e., RPCs and pipelined HTTP streams)
55is negligible.
56
57*TODO(soheil)*: Add benchmarks.
58
59## Limitations
60* *TLS*: `net/http` uses a type assertion to identify TLS connections; since
61cmux's lookahead-implementing connection wraps the underlying TLS connection,
62this type assertion fails.
63Because of that, you can serve HTTPS using cmux but `http.Request.TLS`
64would not be set in your handlers.
65
66* *Different Protocols on The Same Connection*: `cmux` matches the connection
67when it's accepted. For example, one connection can be either gRPC or REST, but
68not both. That is, we assume that a client connection is either used for gRPC
69or REST.
70
71* *Java gRPC Clients*: Java gRPC client blocks until it receives a SETTINGS
72frame from the server. If you are using the Java client to connect to a cmux'ed
73gRPC server please match with writers:
74```go
75grpcl := m.MatchWithWriters(cmux.HTTP2MatchHeaderFieldSendSettings("content-type", "application/grpc"))
76```
77
78# Copyright and License
79Copyright 2016 The CMux Authors. All rights reserved.
80
81See [CONTRIBUTORS](https://github.com/soheilhy/cmux/blob/master/CONTRIBUTORS)
82for the CMux Authors. Code is released under
83[the Apache 2 license](https://github.com/soheilhy/cmux/blob/master/LICENSE).
View as plain text