Add docs for the Java gRPC client

As reported in issue #22 reports that Java gRPC clients cannot
handshake with cmux'ed gRPC server, since the client does not
immediately send a header with the content-type field. The reason
is that the java client, block on receiving the first SETTING
frame.

Add MatchWriter that can match and write on the connection. Implement
a MatchWriter that writes a SETTING frame once it receives a SETTING
frame.

.travis.yml

@@ -1,22 +1,27 @@
 language: go
 
 go:
-  - 1.3
-  - 1.4
   - 1.5
   - 1.6
+  - tip
+
+matrix:
+  allow_failures:
+    - go: tip
 
 gobuild_args: -race
 
 before_install:
-  - go get -u github.com/golang/lint/golint
+  - if [[ $TRAVIS_GO_VERSION == 1.6* ]]; then go get -u github.com/kisielk/errcheck; fi
-  - if [[ $TRAVIS_GO_VERSION == 1.5* ]]; then go get -u github.com/kisielk/errcheck; fi
+  - if [[ $TRAVIS_GO_VERSION == 1.6* ]]; then go get -u github.com/golang/lint/golint; fi
-  - go get -u golang.org/x/tools/cmd/vet
 
 before_script:
   - '! gofmt -s -l . | read'
-  - golint ./...
   - echo $TRAVIS_GO_VERSION
-  - if [[ $TRAVIS_GO_VERSION == 1.5* ]]; then errcheck ./...; fi
+  - if [[ $TRAVIS_GO_VERSION == 1.6* ]]; then golint ./...; fi
-  - go vet .
+  - if [[ $TRAVIS_GO_VERSION == 1.6* ]]; then errcheck ./...; fi
-  - go tool vet --shadow .
+  - if [[ $TRAVIS_GO_VERSION == 1.6* ]]; then go tool vet .; fi
+  - if [[ $TRAVIS_GO_VERSION == 1.6* ]]; then go tool vet --shadow .; fi
+
+script:
+  - go test -v ./...

README.md

@@ -67,3 +67,10 @@ would not be set in your handlers.
 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"))
+```

buffer.go

@@ -1,57 +1,49 @@
 package cmux
 
-import "io"
+import (
+	"bytes"
+	"io"
+)
 
-var _ io.ReadWriter = (*buffer)(nil)
+// bufferedReader is an optimized implementation of io.Reader that behaves like
-
+// ```
-type buffer struct {
+// io.MultiReader(bytes.NewReader(buffer.Bytes()), io.TeeReader(source, buffer))
-	read int
+// ```
-	data []byte
+// without allocating.
+type bufferedReader struct {
+	source     io.Reader
+	buffer     bytes.Buffer
+	bufferRead int
+	bufferSize int
+	sniffing   bool
+	lastErr    error
 }
 
-// From the io.Reader documentation:
+func (s *bufferedReader) Read(p []byte) (int, error) {
-//
+	if s.bufferSize > s.bufferRead {
-// When Read encounters an error or end-of-file condition after
+		// If we have already read something from the buffer before, we return the
-// successfully reading n > 0 bytes, it returns the number of
+		// same data and the last error if any. We need to immediately return,
-// bytes read.  It may return the (non-nil) error from the same call
+		// otherwise we may block for ever, if we try to be smart and call
-// or return the error (and n == 0) from a subsequent call.
+		// source.Read() seeking a little bit of more data.
-// An instance of this general case is that a Reader returning
+		bn := copy(p, s.buffer.Bytes()[s.bufferRead:s.bufferSize])
-// a non-zero number of bytes at the end of the input stream may
+		s.bufferRead += bn
-// return either err == EOF or err == nil.  The next Read should
+		return bn, s.lastErr
-// return 0, EOF.
-//
-// This function implements the latter behaviour, returning the
-// (non-nil) error from the same call.
-func (b *buffer) Read(p []byte) (int, error) {
-	var err error
-	n := copy(p, b.data[b.read:])
-	b.read += n
-	if b.read == len(b.data) {
-		err = io.EOF
-	}
-	return n, err
 	}
 
-func (b *buffer) Len() int {
+	// If there is nothing more to return in the sniffed buffer, read from the
-	return len(b.data) - b.read
+	// source.
+	sn, sErr := s.source.Read(p)
+	if sn > 0 && s.sniffing {
+		s.lastErr = sErr
+		if wn, wErr := s.buffer.Write(p[:sn]); wErr != nil {
+			return wn, wErr
+		}
+	}
+	return sn, sErr
 }
 
-func (b *buffer) resetRead() {
+func (s *bufferedReader) reset(snif bool) {
-	b.read = 0
+	s.sniffing = snif
-}
+	s.bufferRead = 0
-
+	s.bufferSize = s.buffer.Len()
-// From the io.Writer documentation:
-//
-// Write writes len(p) bytes from p to the underlying data stream.
-// It returns the number of bytes written from p (0 <= n <= len(p))
-// and any error encountered that caused the write to stop early.
-// Write must return a non-nil error if it returns n < len(p).
-// Write must not modify the slice data, even temporarily.
-//
-// Implementations must not retain p.
-//
-// In a previous incarnation, this implementation retained the incoming slice.
-func (b *buffer) Write(p []byte) (int, error) {
-	b.data = append(b.data, p...)
-	return len(p), nil
 }

buffer_test.go

@@ -1,113 +0,0 @@
-package cmux
-
-import (
-	"bytes"
-	"io"
-	"testing"
-)
-
-func TestWriteNoModify(t *testing.T) {
-	var b buffer
-
-	const origWriteByte = 0
-	const postWriteByte = 1
-
-	writeBytes := []byte{origWriteByte}
-	if _, err := b.Write(writeBytes); err != nil {
-		t.Fatal(err)
-	}
-	writeBytes[0] = postWriteByte
-	readBytes := make([]byte, 1)
-	if _, err := b.Read(readBytes); err != io.EOF {
-		t.Fatal(err)
-	}
-
-	if readBytes[0] != origWriteByte {
-		t.Fatalf("expected to read %x, but read %x; buffer retained passed-in slice", origWriteByte, postWriteByte)
-	}
-}
-
-const writeString = "deadbeef"
-
-func TestBuffer(t *testing.T) {
-	writeBytes := []byte(writeString)
-
-	const numWrites = 10
-
-	var b buffer
-	for i := 0; i < numWrites; i++ {
-		n, err := b.Write(writeBytes)
-		if err != nil && err != io.EOF {
-			t.Fatal(err)
-		}
-		if n != len(writeBytes) {
-			t.Fatalf("cannot write all the bytes: want=%d got=%d", len(writeBytes), n)
-		}
-	}
-
-	for j := 0; j < 2; j++ {
-		readBytes := make([]byte, len(writeBytes))
-		for i := 0; i < numWrites; i++ {
-			n, err := b.Read(readBytes)
-			if i == numWrites-1 {
-				// The last read should report EOF.
-				if err != io.EOF {
-					t.Fatal(err)
-				}
-			} else if err != nil {
-				t.Fatal(err)
-			}
-			if n != len(readBytes) {
-				t.Fatalf("cannot read all the bytes: want=%d got=%d", len(readBytes), n)
-			}
-			if !bytes.Equal(writeBytes, readBytes) {
-				t.Errorf("different bytes read: want=%d got=%d", writeBytes, readBytes)
-			}
-		}
-		n, err := b.Read(readBytes)
-		if err != io.EOF {
-			t.Errorf("expected EOF")
-		}
-		if n != 0 {
-			t.Errorf("expected buffer to be empty, but got %d bytes", n)
-		}
-
-		b.resetRead()
-	}
-}
-
-func TestBufferOffset(t *testing.T) {
-	writeBytes := []byte(writeString)
-
-	var b buffer
-	n, err := b.Write(writeBytes)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if n != len(writeBytes) {
-		t.Fatalf("cannot write all the bytes: want=%d got=%d", len(writeBytes), n)
-	}
-
-	const readSize = 2
-
-	numReads := len(writeBytes) / readSize
-
-	for i := 0; i < numReads; i++ {
-		readBytes := make([]byte, readSize)
-		n, err := b.Read(readBytes)
-		if i == numReads-1 {
-			// The last read should report EOF.
-			if err != io.EOF {
-				t.Fatal(err)
-			}
-		} else if err != nil {
-			t.Fatal(err)
-		}
-		if n != readSize {
-			t.Fatalf("cannot read the bytes: want=%d got=%d", readSize, n)
-		}
-		if got := writeBytes[i*readSize : i*readSize+readSize]; !bytes.Equal(got, readBytes) {
-			t.Fatalf("different bytes read: want=%s got=%s", readBytes, got)
-		}
-	}
-}

cmux.go

@@ -10,6 +10,9 @@ import (
 // Matcher matches a connection based on its content.
 type Matcher func(io.Reader) bool
 
+// MatchWriter is a match that can also write response (say to do handshake).
+type MatchWriter func(io.Writer, io.Reader) bool
+
 // ErrorHandler handles an error and returns whether
 // the mux should continue serving the listener.
 type ErrorHandler func(error) bool
@@ -60,6 +63,14 @@ type CMux interface {
 	//
 	// 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
@@ -68,7 +79,7 @@ type CMux interface {
 }
 
 type matchersListener struct {
-	ss []Matcher
+	ss []MatchWriter
 	l  muxListener
 }
 
@@ -80,7 +91,22 @@ type cMux struct {
 	sls    []matchersListener
 }
 
+func matchersToMatchWriters(matchers []Matcher) []MatchWriter {
+	mws := make([]MatchWriter, 0, len(matchers))
+	for _, m := range matchers {
+		mws = append(mws, func(w io.Writer, r io.Reader) bool {
+			return m(r)
+		})
+	}
+	return mws
+}
+
 func (m *cMux) Match(matchers ...Matcher) net.Listener {
+	mws := matchersToMatchWriters(matchers)
+	return m.MatchWithWriters(mws...)
+}
+
+func (m *cMux) MatchWithWriters(matchers ...MatchWriter) net.Listener {
 	ml := muxListener{
 		Listener: m.root,
 		connc:    make(chan net.Conn, m.bufLen),
@@ -125,9 +151,9 @@ func (m *cMux) serve(c net.Conn, donec <-chan struct{}, wg *sync.WaitGroup) {
 	muc := newMuxConn(c)
 	for _, sl := range m.sls {
 		for _, s := range sl.ss {
-			matched := s(muc.sniffer())
+			matched := s(muc.Conn, muc.startSniffing())
-			muc.reset()
 			if matched {
+				muc.doneSniffing()
 				select {
 				case sl.l.connc <- muc:
 				case <-donec:
@@ -177,12 +203,13 @@ func (l muxListener) Accept() (net.Conn, error) {
 // MuxConn wraps a net.Conn and provides transparent sniffing of connection data.
 type MuxConn struct {
 	net.Conn
-	buf buffer
+	buf bufferedReader
 }
 
 func newMuxConn(c net.Conn) *MuxConn {
 	return &MuxConn{
 		Conn: c,
+		buf:  bufferedReader{source: c},
 	}
 }
 
@@ -196,22 +223,15 @@ func newMuxConn(c net.Conn) *MuxConn {
 // a non-zero number of bytes at the end of the input stream may
 // return either err == EOF or err == nil.  The next Read should
 // return 0, EOF.
-//
-// This function implements the latter behaviour, returning the
-// (non-nil) error from the same call.
 func (m *MuxConn) Read(p []byte) (int, error) {
-	n1, err := m.buf.Read(p)
+	return m.buf.Read(p)
-	if err != io.EOF {
-		return n1, err
-	}
-	n2, err := m.Conn.Read(p[n1:])
-	return n1 + n2, err
 }
 
-func (m *MuxConn) sniffer() io.Reader {
+func (m *MuxConn) startSniffing() io.Reader {
-	return io.MultiReader(&m.buf, io.TeeReader(m.Conn, &m.buf))
+	m.buf.reset(true)
+	return &m.buf
 }
 
-func (m *MuxConn) reset() {
+func (m *MuxConn) doneSniffing() {
-	m.buf.resetRead()
+	m.buf.reset(false)
 }

cmux_test.go

@@ -284,7 +284,13 @@ func TestHTTP2(t *testing.T) {
 		t.Fatal(err)
 	}
 	var b [len(http2.ClientPreface)]byte
-	if _, err := muxedConn.Read(b[:]); err != io.EOF {
+	var n int
+	// We have the sniffed buffer first...
+	if n, err = muxedConn.Read(b[:]); err == io.EOF {
+		t.Fatal(err)
+	}
+	// and then we read from the source.
+	if _, err = muxedConn.Read(b[n:]); err != io.EOF {
 		t.Fatal(err)
 	}
 	if string(b[:]) != http2.ClientPreface {

matchers.go

@@ -94,7 +94,16 @@ func HTTP1HeaderField(name, value string) Matcher {
 // headers frame.
 func HTTP2HeaderField(name, value string) Matcher {
 	return func(r io.Reader) bool {
-		return matchHTTP2Field(r, name, value)
+		return matchHTTP2Field(ioutil.Discard, r, name, value)
+	}
+}
+
+// HTTP2MatchHeaderFieldSendSettings matches the header field and writes the
+// settings to the server. Prefer HTTP2HeaderField over this one, if the client
+// does not block on receiving a SETTING frame.
+func HTTP2MatchHeaderFieldSendSettings(name, value string) MatchWriter {
+	return func(w io.Writer, r io.Reader) bool {
+		return matchHTTP2Field(w, r, name, value)
 	}
 }
 
@@ -116,12 +125,12 @@ func matchHTTP1Field(r io.Reader, name, value string) (matched bool) {
 	return req.Header.Get(name) == value
 }
 
-func matchHTTP2Field(r io.Reader, name, value string) (matched bool) {
+func matchHTTP2Field(w io.Writer, r io.Reader, name, value string) (matched bool) {
 	if !hasHTTP2Preface(r) {
 		return false
 	}
 
-	framer := http2.NewFramer(ioutil.Discard, r)
+	framer := http2.NewFramer(w, r)
 	hdec := hpack.NewDecoder(uint32(4<<10), func(hf hpack.HeaderField) {
 		if hf.Name == name && hf.Value == value {
 			matched = true
@@ -134,6 +143,10 @@ func matchHTTP2Field(r io.Reader, name, value string) (matched bool) {
 		}
 
 		switch f := f.(type) {
+		case *http2.SettingsFrame:
+			if err := framer.WriteSettings(); err != nil {
+				return false
+			}
 		case *http2.HeadersFrame:
 			if _, err := hdec.Write(f.HeaderBlockFragment()); err != nil {
 				return false