cockroachdb / cmux

Connection multiplexer for GoLang: serve different services on the same port!

cmux: Connection Mux

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:

// 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()
s.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()

There are more examples on GoDoc.

Performance

Since we are only matching the very first bytes of a connection, the performance overhead on long-lived connections (i.e., RPCs and pipelined HTTP streams) is negligible.

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. This means you can serve HTTPS using cmux but http.Request.TLS will not be set in your handlers. If you are able to wrap TLS around cmux, you can work around this limitation. See https://github.com/cockroachdb/cockroach/commit/83caba2 for an example of this approach.

• 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.

Copyright and License

Copyright 2016 The CMux Authors. All rights reserved.

See CONTRIBUTORS for the CMux Authors. Code is released under the Apache 2 license.

cmux's Issues

MatchWithWriters not present - hanging java clients

thanks for the connection multiplexer it is really useful . recently we found that java clients couldn't connect to our grpc server . I see this issue is fixed in https://github.com/soheilhy/cmux and we have MatchWithWriters present there . So it works with it. But the repo here doesn't have that function . When is that going to merge with this cockroachdb cmux.

or which one do you recommend using https://github.com/soheilhy/cmux or https://github.com/cockroachdb/cmux/

Please advise.

Also if i use java client with tls and and a go server with tls it hangs even if i set
grpcl := m.MatchWithWriters(cmux.HTTP2MatchHeaderFieldSendSettings("content-type", "application/grpc"))

If i dont use tls for authentication then it works. We have wrapped the tls over cmux so tls would be happening first. Is there any workaround for that ?

Thanks

Please add copyright statement

There is no copyright(s) documentation anywhere in source. Please consider adding copyright statement to README (e.g. Copyright 2015-2016 Name Surname <[email protected]>).

See relevant upstream bug:

soheilhy#28

Thanks.

Please tag releases

Please consider assigning version numbers and tagging releases. Tags/releases
are useful for downstream package maintainers (in Debian and other distributions) to export source tarballs, automatically track new releases and to declare dependencies between packages. Read more in the Debian Upstream Guide.

Versioning provides additional benefits to encourage vendoring of a particular (e.g. latest stable) release contrary to random unreleased snapshots.

Thank you.

See also

• http://semver.org/
• https://en.wikipedia.org/wiki/Software_versioning