connect

package module
v2.0.0-...-fc8db53 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

README

Connect

Build GoDoc Slack OpenSSF Best Practices

Connect is a slim library for building browser and gRPC-compatible HTTP APIs. You write a short Protocol Buffer schema and implement your application logic, and Connect generates code to handle marshaling, routing, compression, and content type negotiation. It also generates an idiomatic, type-safe client. Handlers and clients support three protocols: gRPC, gRPC-Web, and Connect's own protocol.

The Connect protocol is a simple protocol that works over HTTP/1.1 or HTTP/2. It takes the best portions of gRPC and gRPC-Web, including streaming, and packages them into a protocol that works equally well in browsers, monoliths, and microservices. Calling a Connect API is as easy as using curl. Try it with our live demo:

curl \
    --header "Content-Type: application/json" \
    --data '{"sentence": "I feel happy."}' \
    https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Say

Handlers and clients also support the gRPC and gRPC-Web protocols, including streaming, headers, trailers, and error details. gRPC-compatible server reflection and health checks are available as standalone packages. Instead of cURL, we could call our API with a gRPC client:

go install github.com/bufbuild/buf/cmd/buf@latest
buf curl --protocol grpc \
    --data '{"sentence": "I feel happy."}' \
    https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Say

Under the hood, Connect is just Protocol Buffers and the standard library: no custom HTTP implementation, no new name resolution or load balancing APIs, and no surprises. Everything you already know about net/http still applies, and any package that works with an http.Server, http.Client, or http.Handler also works with Connect.

For more on Connect, see the announcement blog post, the documentation on connectrpc.com (especially the Getting Started guide for Go), the demo service, or the protocol specification.

A small example

Curious what all this looks like in practice? From a Protobuf schema, we generate a small RPC package. Using that package, we can build a server. This example is available at internal/example:

package main

import (
  "context"
  "log"
  "net/http"

  "connectrpc.com/connect/v2"
  "connectrpc.com/connect/v2/connecthttp"
  pingv1 "connectrpc.com/connect/v2/internal/gen/connect/ping/v1"
  "connectrpc.com/connect/v2/internal/gen/connect/ping/v1/pingv1connect"
  "connectrpc.com/validate/v2"
)

type PingServer struct {
  pingv1connect.UnimplementedPingServiceHandler // returns errors from all methods
}

func (ps *PingServer) Ping(ctx context.Context, req *pingv1.PingRequest) (*pingv1.PingResponse, error) {
  return &pingv1.PingResponse{
    Number: req.Number,
  }, nil
}

func main() {
  // Register services on a *connect.Server, then mount it with connecthttp.
  // Interceptors are arguments to NewServer. Validation via Protovalidate is
  // almost always recommended.
  server := connect.NewServer(validate.NewServerInterceptor())
  pingv1connect.RegisterPingServiceHandler(server, &PingServer{})
  mux := http.NewServeMux()
  connecthttp.Mount(mux, server)
  p := new(http.Protocols)
  p.SetHTTP1(true)
  // For gRPC clients, it's convenient to support HTTP/2 without TLS.
  p.SetUnencryptedHTTP2(true)
  s := &http.Server{
    Addr:      "localhost:8080",
    Handler:   mux,
    Protocols: p,
  }
  if err := s.ListenAndServe(); err != nil {
    log.Fatalf("listen failed: %v", err)
  }
}

With that server running, you can make requests with any gRPC or Connect client. To write a client using Connect:

package main

import (
  "context"
  "log"
  "net/http"

  "connectrpc.com/connect/v2"
  "connectrpc.com/connect/v2/connecthttp"
  pingv1 "connectrpc.com/connect/v2/internal/gen/connect/ping/v1"
  "connectrpc.com/connect/v2/internal/gen/connect/ping/v1/pingv1connect"
)

func main() {
  client := connect.NewClient(
    connecthttp.NewTransport(http.DefaultClient, "http://localhost:8080"),
  )
  pingClient := pingv1connect.NewPingServiceClient(client)
  req := &pingv1.PingRequest{Number: 42}
  res, err := pingClient.Ping(context.Background(), req)
  if err != nil {
    log.Fatalln(err)
  }
  log.Println(res)
}

Of course, http.ListenAndServe and http.DefaultClient aren't fit for production use! See Connect's deployment docs for a guide to configuring timeouts, connection pools, observability, and h2c.

Migrating from v1

If you are migrating from v1 to v2, check out our migration guide.

This project follows semantic versioning. The module /v2 suffix is part of the module connectrpc.com/connect/v2.

Ecosystem

Status

This module, connectrpc.com/connect/v2, is in beta. The v2 module will be published on the main branch of the repository when released.

Support and versioning

connect-go supports:

  • The two most recent major releases of Go (the same versions of Go that continue to receive security patches).
  • APIv2 of Protocol Buffers in Go (google.golang.org/protobuf).

Within those parameters, connect-go follows semantic versioning.

Module connectrpc.com/connect is the v1 module. It remains stable and supported indefinitely. The v1 module lives on the v1 branch. See the v2 guide for an overview of what changed and why.

Offered under the Apache 2 license.

Documentation

Overview

Package connect is a slim RPC framework built on Protocol Buffers and net/http. In addition to supporting its own protocol, Connect handlers and clients are wire-compatible with gRPC and gRPC-Web, including streaming.

This documentation is intended to explain each type and function in isolation. Walkthroughs, FAQs, and other narrative docs are available on the Connect website, and there's a working demonstration service on Github.

Index

Constants

View Source 
const (
	// CodecNameProto is the protocol token for protobuf binary encoding.
	CodecNameProto = "proto"
	// CodecNameJSON is the protocol token for protobuf JSON encoding.
	CodecNameJSON = "json"
)

Well-known codec names.

View Source 
const (
	// CompressionNameIdentity is the token for uncompressed messages. It is
	// named so transport metadata can report "identity" consistently even
	// though no compressor is needed.
	CompressionNameIdentity = "identity"
	// CompressionNameGzip is the token for gzip compression.
	CompressionNameGzip = "gzip"
	// CompressionNameBr is the token for Brotli compression. The core package
	// defines the name so transports and compressor packages can agree on the
	// token. It does not provide a Brotli compressor.
	CompressionNameBr = "br"
	// CompressionNameZstd is the token for Zstandard compression. The core
	// package defines the name so transports and compressor packages can agree
	// on the token. It does not provide a Zstandard compressor.
	CompressionNameZstd = "zstd"
)

Well-known compression names.

View Source 
const (
	// ProtocolNameConnect is the token for the Connect protocol.
	ProtocolNameConnect = "connect"
	// ProtocolNameGRPC is the token for the gRPC protocol.
	ProtocolNameGRPC = "grpc"
	// ProtocolNameGRPCWeb is the token for the gRPC-Web protocol.
	ProtocolNameGRPCWeb = "grpcweb"
)

Well-known protocol names reported by CallInfo.Protocol.

View Source 
const Version = "2.0.0-dev"

Version is the semantic version of the connect module.

Variables

This section is empty.

Functions

func DecodeBinaryHeader 

func DecodeBinaryHeader(data string) ([]byte, error)

DecodeBinaryHeader base64-decodes the data. It can decode padded or unpadded values. Following usual HTTP semantics, multiple base64-encoded values may be joined with a comma. When receiving such comma-separated values, split them with strings.Split before calling DecodeBinaryHeader.

Binary headers sent using the Connect, gRPC, and gRPC-Web protocols have keys ending in "-Bin".

func EncodeBinaryHeader 

func EncodeBinaryHeader(data []byte) string

EncodeBinaryHeader base64-encodes the data. It always emits unpadded values.

In the Connect, gRPC, and gRPC-Web protocols, binary headers must have keys ending in "-Bin".

Types

type CallInfo 

type CallInfo struct {
	// Spec describes the RPC procedure.
	Spec Spec
	// PeerAddr is the remote peer's address, or empty when the transport has
	// no network peer.
	PeerAddr string
	// Protocol is the wire protocol, such as "connect", "grpc", or "grpcweb".
	Protocol string
	// Codec is the codec name, such as "proto" or "json".
	Codec string
	// RequestEncoding is the request compression, "identity" when
	// uncompressed.
	RequestEncoding string
	// ResponseEncoding is the response compression, "identity" when
	// uncompressed.
	ResponseEncoding string
	// SendStats holds byte counts for the most recent Send.
	SendStats MessageStats
	// ReceiveStats holds byte counts for the most recent Receive.
	ReceiveStats MessageStats
	// TransportInfo is optional transport-specific metadata, such as
	// [connectrpc.com/connect/v2/connecthttp.ClientInfo] or
	// [connectrpc.com/connect/v2/connecthttp.ServerInfo].
	TransportInfo any
	// contains filtered or unexported fields
}

CallInfo describes an RPC as it runs. Clients reach it with NewClientContext, servers with CallInfoForServerContext. The two sides use separate context keys, so a handler's outbound calls don't share its inbound metadata.

The transport populates the fields: request-side fields before dispatch, response-side fields and stats as messages flow. On a streaming RPC, reading a field before the matching Send or Receive returns races the transport.

func CallInfoForClientContext 

func CallInfoForClientContext(ctx context.Context) (*CallInfo, bool)

CallInfoForClientContext returns the client-side CallInfo attached to ctx, if there is one. Client call methods attach a fresh CallInfo before invoking the interceptor chain when ctx does not already carry one, so client interceptors and the Transport can rely on it being present. Outside a Client call, it reports false unless the caller used NewClientContext.

func CallInfoForServerContext 

func CallInfoForServerContext(ctx context.Context) (*CallInfo, bool)

CallInfoForServerContext returns the server-side CallInfo attached by Server.Call before invoking interceptors and generated handlers, if there is one. It reports false if the call did not come through Server.Call (e.g., a raw ServerFunc invocation in a test).

func NewClientContext 

func NewClientContext(ctx context.Context) (context.Context, *CallInfo)

NewClientContext attaches a fresh client-side CallInfo to ctx and returns both. Use it to set request metadata before issuing an RPC, or to read response metadata after the call. A reused handle reports the most recent call. For concurrent calls, derive a separate context per call.

func (*CallInfo) RequestHeader 

func (c *CallInfo) RequestHeader() *Header

RequestHeader returns the request headers. The client sets them before the first Send, and the server reads them.

func (*CallInfo) ResponseHeader 

func (c *CallInfo) ResponseHeader() *Header

ResponseHeader returns the response headers. The server sets them before its first Send, and the client reads them once the response arrives.

func (*CallInfo) ResponseTrailer 

func (c *CallInfo) ResponseTrailer() *Header

ResponseTrailer returns the response trailers. The server sets them before the stream ends, and the client reads them after receiving to io.EOF.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client bundles a Transport with the client-side interceptor chain. Generated service clients hold a *Client and dispatch every RPC through one of the Call methods.

The interceptor chain is applied once in NewClient, producing one prebuilt ClientFunc.

func NewClient 

func NewClient(transport Transport, interceptors ...ClientInterceptor) *Client

NewClient returns a Client that dispatches RPCs over transport. The interceptors fire in argument order. The first wraps the outermost call. Interceptors that need per-message behavior wrap the ClientStream that next returns.

The interceptor chain is applied here, once, not on every RPC. Per-RPC state belongs in the ClientFunc an interceptor returns, or in a ClientStream wrapper, not in the interceptor function itself.

func (*Client) CallClientStream 

func (c *Client) CallClientStream(ctx context.Context, spec Spec) (ClientStream, error)

CallClientStream opens a stream for spec for client-streaming or bidi RPCs. The returned ClientStream is wrapped by interceptors when any are configured.

The stream's underlying resources are released automatically when ClientStream.Receive returns io.EOF or the RPC context is canceled. To abandon a stream before reading to completion, cancel the context or call ClientStream.Close.

func (*Client) CallServerStream 

func (c *Client) CallServerStream(ctx context.Context, spec Spec, req any) (ClientStream, error)

CallServerStream opens a stream for spec, sends the single request, closes the send side, and returns the stream for the caller to read responses from. The returned ClientStream is wrapped by interceptors when any are configured.

Its resources are released automatically when ClientStream.Receive returns io.EOF or the RPC context is canceled. To abandon the stream early, cancel the context or call ClientStream.Close.

func (*Client) CallUnary 

func (c *Client) CallUnary(ctx context.Context, spec Spec, req, res any) (err error)

CallUnary opens a stream for spec, sends req, closes the send side, and reads a single response into res.

The initialization passes through the interceptor chain. The full ClientStream.Send, ClientStream.CloseSend, and ClientStream.Receive sequence is then executed on the resulting stream. Receive reads the response to io.EOF, which releases the stream's resources.

type ClientFunc 

type ClientFunc func(ctx context.Context, spec Spec) (ClientStream, error)

ClientFunc opens a ClientStream for an RPC. Interceptors wrap one ClientFunc to produce another. The innermost function invokes the Transport to establish the connection and initialize the stream.

type ClientInterceptor 

type ClientInterceptor func(next ClientFunc) ClientFunc

ClientInterceptor wraps a ClientFunc. It may return an error without calling next to short-circuit the RPC.

Unlike server interceptors, client interceptors wrap the initialization of the stream rather than the full execution of the RPC. This model is identical across unary and streaming calls. Because next opens the stream, deriving a new context and passing it to next propagates that context to the Transport and the stream. To observe or modify messages, interceptors call next and wrap the returned ClientStream. To observe the end of the RPC, wrap both Close and Receive: streaming callers may finish at io.EOF without calling Close.

NewClient applies the chain when the client is constructed, so the interceptor function runs once, not once per RPC. Keep per-RPC state in the returned ClientFunc or stream wrapper.

type ClientStream 

type ClientStream interface {
	// SendHeaders flushes the request headers and opens the stream without
	// sending a request message. The first Send or Receive does this
	// implicitly; call SendHeaders only to flush eagerly, for example to let
	// the server begin work, surface connection errors before the first
	// message, or record timing. It is idempotent.
	SendHeaders() error
	// Send sends msg as the next request message.
	Send(msg any) error
	// CloseSend closes the request side of the stream. It is idempotent.
	CloseSend() error
	// Receive reads the next response message into msg. It reports clean
	// receive-side completion with an error that matches io.EOF under errors.Is.
	// Reading to io.EOF releases the stream's resources; to abandon a stream
	// earlier, cancel the call's context or call Close.
	Receive(msg any) error
	// Close releases the stream's resources, unblocking a pending Receive and
	// tearing the stream down. It may be called concurrently with Receive,
	// typically as defer stream.Close(). It is idempotent. After Close, the
	// stream must not be used again.
	Close() error
}

ClientStream is the client-side view of a single in-flight RPC.

A caller drives the stream by sending request messages, closing the send side with CloseSend, and receiving response messages until Receive reports the end of the response stream with an error matching io.EOF under errors.Is. Reading to io.EOF releases the stream's resources and makes the response trailers available on the call's CallInfo. To abandon a stream before io.EOF, cancel the context passed to the Client call: that releases resources and unblocks any pending operation. Client.CallUnary drives this full sequence internally.

The first Send or Receive flushes the request headers from CallInfo.RequestHeader and opens the stream. Call ClientStream.SendHeaders to flush them eagerly without sending a message. After the headers are flushed, later mutations to the request headers may not affect the request.

Send transmits request messages, and Receive reads response messages. The msg passed to Send and Receive must match the message type described by the stream's Spec. Generated wrappers expose typed methods for the legal operations, but raw stream users must follow Spec.StreamType themselves.

A stream supports one active send-side operation and one active receive-side operation at a time, and the two sides may run concurrently. Do not call Send concurrently with Send or CloseSend, and do not call Receive concurrently with Receive.

RPC status and protocol errors returned by streams can be inspected with errors.As into *Error or classified with CodeOf. Clean receive-side completion is reported by an error that matches io.EOF under errors.Is. Context cancellation may be reported directly as context.Canceled or context.DeadlineExceeded, or as an *Error whose cause matches one of those errors.

The stream does not expose Spec or CallInfo. The Spec is passed alongside the stream into ClientFunc, and the CallInfo is reached through ctx via CallInfoForClientContext.

type Code 

type Code uint32

Code is a Connect error code. 

const (

	// CodeCanceled indicates that the operation was canceled, typically by the
	// caller.
	CodeCanceled Code = 1

	// CodeUnknown indicates that the operation failed for an unknown reason.
	CodeUnknown Code = 2

	// CodeInvalidArgument indicates that client supplied an invalid argument.
	CodeInvalidArgument Code = 3

	// CodeDeadlineExceeded indicates that deadline expired before the operation
	// could complete.
	CodeDeadlineExceeded Code = 4

	// CodeNotFound indicates that some requested entity (for example, a file or
	// directory) was not found.
	CodeNotFound Code = 5

	// CodeAlreadyExists indicates that client attempted to create an entity (for
	// example, a file or directory) that already exists.
	CodeAlreadyExists Code = 6

	// CodePermissionDenied indicates that the caller doesn't have permission to
	// execute the specified operation.
	CodePermissionDenied Code = 7

	// CodeResourceExhausted indicates that some resource has been exhausted. For
	// example, a per-user quota may be exhausted or the entire file system may
	// be full.
	CodeResourceExhausted Code = 8

	// CodeFailedPrecondition indicates that the system is not in a state
	// required for the operation's execution.
	CodeFailedPrecondition Code = 9

	// CodeAborted indicates that operation was aborted by the system, usually
	// because of a concurrency issue such as a sequencer check failure or
	// transaction abort.
	CodeAborted Code = 10

	// CodeOutOfRange indicates that the operation was attempted past the valid
	// range (for example, seeking past end-of-file).
	CodeOutOfRange Code = 11

	// CodeUnimplemented indicates that the operation isn't implemented,
	// supported, or enabled in this service.
	CodeUnimplemented Code = 12

	// CodeInternal indicates that some invariants expected by the underlying
	// system have been broken. This code is reserved for serious errors.
	CodeInternal Code = 13

	// CodeUnavailable indicates that the service is currently unavailable. This
	// is usually temporary, so clients can back off and retry idempotent
	// operations.
	CodeUnavailable Code = 14

	// CodeDataLoss indicates that the operation has resulted in unrecoverable
	// data loss or corruption.
	CodeDataLoss Code = 15

	// CodeUnauthenticated indicates that the request does not have valid
	// authentication credentials for the operation.
	CodeUnauthenticated Code = 16
)

Standard Connect RPC codes. Code.String returns the lowercase protocol token for each code.

func CodeOf 

func CodeOf(err error) Code

CodeOf returns the Connect code carried by err. If err does not wrap an *Error, CodeOf returns CodeUnknown. Passing nil is not meaningful and also returns CodeUnknown.

func (Code) MarshalText 

func (c Code) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Code) String 

func (c Code) String() string

String returns the lowercase protocol token for c.

func (*Code) UnmarshalText 

func (c *Code) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type Codec 

type Codec interface {
	// Name returns the protocol codec token, such as "proto" or "json".
	Name() string
	// MarshalWrite encodes msg to dst. The encoding must be complete when
	// MarshalWrite returns. Any write error from dst must be returned
	// directly or wrapped with %w.
	MarshalWrite(ctx context.Context, dst io.Writer, msg any) error
	// UnmarshalRead decodes one message from src into msg. src is bounded to
	// that message and reports [io.EOF] once the payload is consumed. Any read
	// error from src must be returned directly or wrapped with %w. The transport
	// drains any unread bytes once it returns.
	UnmarshalRead(ctx context.Context, src io.Reader, msg any) error
}

Codec marshals and unmarshals RPC messages. Implementations must be safe for concurrent use. Method contexts carry per-call values. Codecs are not required to observe cancellation.

Transports pass io.Writer and io.Reader so codecs may stream when their encoding supports it. Codecs that need contiguous input or output should buffer internally. Writers from this module also expose the AvailableBuffer and Grow methods of bytes.Buffer for append-style encoders.

dst and src are valid only for the duration of the call. A codec must not retain or use either after it returns.

type Compressor 

type Compressor interface {
	// Name returns the content-encoding token, such as "gzip".
	Name() string
	// Compress returns a writer that writes compressed bytes to dst. Closing
	// the writer flushes buffered data and releases resources. Callers must
	// close the writer exactly once and must not use it after Close.
	Compress(dst io.Writer) (io.WriteCloser, error)
	// Decompress returns a reader for the decompressed form of src. Closing
	// the reader releases resources without closing src. Callers must close
	// the reader exactly once, even if it was not fully consumed, and must not
	// use it after Close.
	Decompress(src io.Reader) (io.ReadCloser, error)
}

Compressor compresses and decompresses RPC payloads. Implementations must be safe for concurrent use.

The writers and readers returned by Compressor methods own per-payload state. They are used by one goroutine at a time and must be closed exactly once. Implementations may pool state and recycle it on Close.

The returned writer may retain dst until Close, and the returned reader may retain src until Close. They must not write to dst or read from src after Close. Transports enforce decompressed-size limits by wrapping the reader returned from Decompress.

type Error 

type Error struct {
	// contains filtered or unexported fields
}

Error is the Connect error type. Code, message, and supported detail values may be serialized by transports. Cause and remote are local process metadata and are never serialized.

Handlers fail an RPC by returning an error, but only a locally authored *Error carries its code, message, and details to the wire. Transports must not serialize other errors: clients see only a code, typically CodeUnknown, with no message. Text sent to callers is therefore always constructed intentionally with NewError or Errorf.

func Errorf 

func Errorf(code Code, format string, args ...any) *Error

Errorf returns a new *Error with the given code and a formatted public message. The message is serialized to the wire. Do not include sensitive details.

Errorf uses fmt.Sprintf and does not attach wrapped errors. Use Error.WithCause for local-only causes.

func NewError 

func NewError(code Code, message string) *Error

NewError returns a new *Error with code and a public message. The message is serialized to the wire. Do not include sensitive details.

func (*Error) Code 

func (e *Error) Code() Code

Code returns the Connect error code. If the stored code is zero, Code returns CodeUnknown.

func (*Error) Details 

func (e *Error) Details() []*ErrorDetail

Details returns a copy of the error's detail list. Decode each detail with a codec package, such as connectrpc.com/connect/v2/connectproto.UnmarshalErrorDetail.

func (*Error) Error 

func (e *Error) Error() string

Error returns "code" or "code: message".

func (*Error) IsRemote 

func (e *Error) IsRemote() bool

IsRemote reports whether this error is a peer's RPC verdict rather than the local handler's own. Server transports must not forward a remote Error as the handler's own RPC verdict.

func (*Error) Message 

func (e *Error) Message() string

Message returns the optional human-readable error message serialized on the wire.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap returns the local cause for errors.Is and errors.As. The cause is not serialized.

func (*Error) WithCause 

func (e *Error) WithCause(err error) *Error

WithCause returns a cloned error with err attached as a local cause. Causes are available to errors.Is and errors.As but are not serialized. A nil cause is ignored.

func (*Error) WithDetail 

func (e *Error) WithDetail(detail *ErrorDetail) *Error

WithDetail returns a cloned error with detail appended as a public detail value. Construct details with a codec package, such as connectrpc.com/connect/v2/connectproto.NewErrorDetail. A nil detail is ignored.

func (*Error) WithRemote 

func (e *Error) WithRemote() *Error

WithRemote returns a cloned error marked as a peer's RPC verdict.

type ErrorDetail 

type ErrorDetail struct {
	// Type is the fully-qualified message type name, such as
	// "google.rpc.RetryInfo".
	Type string
	// Value is the serialized message.
	Value []byte
	// Debug is an optional human-readable representation of Value, carried
	// by the Connect protocol as the detail's "debug" JSON. It is best
	// effort: transports may regenerate or omit it.
	Debug []byte
}

ErrorDetail is a self-describing message attached to an *Error. On the Connect, gRPC, and gRPC-Web protocols, details are Protobuf messages: construct them with connectrpc.com/connect/v2/connectproto.NewErrorDetail and decode them with connectrpc.com/connect/v2/connectproto.UnmarshalErrorDetail. 

type Header struct {
	// contains filtered or unexported fields
}

Header is a mutable, case-insensitive, multi-valued string map, mirroring net/http.Header. The zero value is ready to use. Header is not safe for concurrent use.

Keys are canonicalized with textproto.CanonicalMIMEHeaderKey. Transports ignore or overwrite protocol-reserved keys when sending an RPC.

func (*Header) Add 

func (m *Header) Add(key, value string)

Add appends value to key's values.

func (*Header) All 

func (m *Header) All() iter.Seq2[string, []string]

All yields each key and its values in unspecified order. The yielded slices alias the header.

func (*Header) Delete 

func (m *Header) Delete(key string)

Delete removes all values for key.

func (*Header) Get 

func (m *Header) Get(key string) string

Get returns the first value associated with key, or "" if the key has no values.

func (*Header) Has 

func (m *Header) Has(key string) bool

func (*Header) Len 

func (m *Header) Len() int

Len returns the number of keys.

func (*Header) Set 

func (m *Header) Set(key, value string)

Set replaces key's values with value.

func (*Header) SetValues 

func (m *Header) SetValues(key string, values []string)

SetValues replaces key's values with values. It does not copy values.

func (*Header) Values 

func (m *Header) Values(key string) []string

Values returns all values associated with key. The returned slice aliases the header.

type IdempotencyLevel 

type IdempotencyLevel int32

IdempotencyLevel mirrors the protobuf MethodOptions idempotency_level. 

const (
	// IdempotencyUnknown means the schema does not declare an idempotency
	// level.
	IdempotencyUnknown IdempotencyLevel = 0
	// IdempotencyNoSideEffects means the RPC has no side effects. Transports
	// may use this to enable protocol features such as Connect GET.
	IdempotencyNoSideEffects IdempotencyLevel = 1
	// IdempotencyIdempotent means repeated identical requests have the same
	// effect as one request.
	IdempotencyIdempotent IdempotencyLevel = 2
)

IdempotencyLevel values mirror protobuf MethodOptions.idempotency_level.

func (IdempotencyLevel) String 

func (i IdempotencyLevel) String() string

String returns a human-readable idempotency-level name.

type MessageStats 

type MessageStats struct {
	// Size is the uncompressed payload size in bytes.
	Size int
	// CompressedSize is the compressed payload size in bytes. It is zero when
	// the message is uncompressed.
	CompressedSize int
}

MessageStats holds byte counts for one RPC message. The counts exclude envelope framing, HTTP headers, and trailers.

type Method 

type Method struct {
	// Spec describes the RPC procedure being registered.
	Spec Spec
	// Handler serves the RPC described by Spec.
	Handler ServerFunc
}

Method binds a Spec to the ServerFunc that serves it.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server is the procedure-to-method dispatcher. It owns the method registry and the server-side interceptor chain.

func NewServer 

func NewServer(interceptors ...ServerInterceptor) *Server

NewServer returns a dispatcher with no registered methods. The interceptors fire in argument order. The first wraps the outermost call. Interceptors that need per-message behavior should wrap the ServerStream before calling next.

func (*Server) Call 

func (s *Server) Call(ctx context.Context, procedure string, info *CallInfo, stream ServerStream) error

Call dispatches an RPC to the method registered for procedure. Transports build the ServerStream from their wire input, pass the per-RPC CallInfo (or nil to let Call allocate one), and Call attaches it to ctx so user handlers can read it via CallInfoForServerContext. Call returns the method error for the transport to encode in its protocol. It does not finalize protocol state. The transport does that once Call returns. Returns CodeUnimplemented when no method is registered.

func (*Server) Register 

func (s *Server) Register(methods ...Method)

Register stores each method on the dispatcher. Each Method.Handler is wrapped with the server-side interceptor chain so Server.Call is just a map lookup plus one call.

Register panics if two methods have the same Spec.Procedure. Register is intended for setup and must not run concurrently with Server.Register, Server.Specs, or Server.Call.

func (*Server) SetUnknownHandler 

func (s *Server) SetUnknownHandler(fn ServerFunc)

SetUnknownHandler sets the fallback ServerFunc that Server.Call invokes when no method is registered for a procedure. The handler receives a Spec whose Procedure is the requested procedure and whose StreamType is StreamTypeBidi, the most permissive shape, since the cardinality of an unregistered procedure is unknown. Its Schema is nil. The handler is wrapped by the server interceptor chain like a registered method. A nil fn restores the default, which fails the call with CodeUnimplemented.

SetUnknownHandler is intended for setup and must not run concurrently with Server.Call or Server.Register.

func (*Server) Specs 

func (s *Server) Specs() iter.Seq[Spec]

Specs yields the Spec values of registered methods. Transports use this to install per-procedure routes. Specs are yielded in registration order. Do not call Specs concurrently with Server.Register.

type ServerFunc 

type ServerFunc func(ctx context.Context, spec Spec, stream ServerStream) error

ServerFunc serves an RPC on an open ServerStream. Interceptors wrap one ServerFunc to produce another. The innermost function is the registered Method.Handler.

type ServerInterceptor 

type ServerInterceptor func(next ServerFunc) ServerFunc

ServerInterceptor wraps a ServerFunc. It may return an error without calling next to short-circuit the RPC.

Server interceptors surround the full server invocation. To observe or modify individual messages, interceptors can pass a wrapped ServerStream to next.

type ServerStream 

type ServerStream interface {
	// Receive reads the next request message into msg. It reports clean
	// receive-side completion with an error that matches io.EOF under errors.Is.
	Receive(msg any) error
	// SendHeaders flushes the response headers and opens the stream without
	// sending a response message. The first Send does this implicitly; call
	// SendHeaders only to flush eagerly, for example to let the client begin
	// work or surface headers before the first Send. It is idempotent.
	SendHeaders() error
	// Send sends msg as the next response message.
	Send(msg any) error
}

ServerStream is the server-side view of a single in-flight RPC. The Spec is passed alongside the stream into ServerFunc, and the CallInfo is reached through ctx via CallInfoForServerContext.

The first Send flushes the response headers from CallInfo.ResponseHeader. Call ServerStream.SendHeaders to flush them eagerly without sending a response message. After the headers are flushed, later mutations to the response headers may not affect the response.

Receive reads request messages, and Send transmits response messages. The msg passed to Receive and Send must match the message type described by the stream's Spec. Generated wrappers expose typed methods for the legal operations, but raw stream users must follow Spec.StreamType themselves.

A stream supports one active send-side operation and one active receive-side operation at a time, and the two sides may run concurrently. Do not call Send concurrently with Send, and do not call Receive concurrently with Receive.

The server stream has no Close method: the transport finalizes the RPC when the handler returns, encoding the handler's error and any trailers. Handler code ends the RPC by returning, not by closing the stream.

RPC status and protocol errors returned by streams can be inspected with errors.As into *Error or classified with CodeOf. Clean receive-side completion is reported by an error that matches io.EOF under errors.Is. Context cancellation may be reported directly as context.Canceled or context.DeadlineExceeded, or as an *Error whose cause matches one of those errors.

type Spec 

type Spec struct {
	// StreamType describes which side, if any, sends multiple messages.
	// It controls which stream operations generated wrappers expose.
	StreamType StreamType
	// IdempotencyLevel mirrors protobuf MethodOptions.idempotency_level.
	// Transports may use it for protocol features such as Connect GET.
	IdempotencyLevel IdempotencyLevel
	// Schema is opaque method schema information. Protobuf generated code
	// stores a protoreflect.MethodDescriptor. Other schema systems may use
	// their own descriptor types.
	Schema any
	// Procedure is the leading-slash RPC path, such as
	// "/package.Service/Method". Server uses it as the registry key, and
	// HTTP transports use it as the route path.
	Procedure string
}

Spec describes a single RPC procedure. Generated code typically provides one Spec per protobuf method.

type StableCodec 

type StableCodec interface {
	Codec
	// MarshalWriteStable encodes msg deterministically to dst. Messages
	// equivalent under the codec's schema rules must produce identical bytes.
	// The dst writer follows the rules of [Codec.MarshalWrite].
	MarshalWriteStable(ctx context.Context, dst io.Writer, msg any) error
	// IsBinary reports whether MarshalWriteStable writes binary data. Binary
	// encodings are text-encoded before use in URLs.
	IsBinary() bool
}

StableCodec is a Codec with a deterministic encoding. Transports use stable encodings for features such as Connect GET request URLs.

type StreamType 

type StreamType uint8

StreamType describes the directionality of an RPC. 

const (
	// StreamTypeUnary identifies an RPC with one request and one response.
	StreamTypeUnary StreamType = 0b00
	// StreamTypeClient identifies a client-streaming RPC.
	StreamTypeClient StreamType = 0b01
	// StreamTypeServer identifies a server-streaming RPC.
	StreamTypeServer StreamType = 0b10
	// StreamTypeBidi identifies a bidirectional-streaming RPC.
	StreamTypeBidi = StreamTypeClient | StreamTypeServer
)

StreamType values describe the directionality of an RPC.

func (StreamType) String 

func (s StreamType) String() string

String returns a human-readable stream type name.

type Transport 

type Transport interface {
	// NewClientStream opens a client stream for spec.
	NewClientStream(ctx context.Context, spec Spec) (ClientStream, error)
}

Transport is the boundary between Client and an RPC execution environment. A Client passes the RPC Spec to a Transport, then drives the returned ClientStream by sending request messages, closing the send side, receiving response messages, and closing the stream. Generated clients hold a *Client rather than a Transport directly.

connectrpc.com/connect/v2/connecthttp.NewTransport returns a Transport that sends RPCs over Connect, gRPC, or gRPC-Web on net/http. Other implementations can dispatch directly to a Server, use a test double, or adapt another wire protocol without regenerating clients.

Source Files

View all Source files

Directories

Path Synopsis
cmd
connect-go-v2-migrate command
Command connect-go-v2-migrate rewrites Go source code to migrate from connectrpc.com/connect to connectrpc.com/connect/v2.
 Command connect-go-v2-migrate rewrites Go source code to migrate from connectrpc.com/connect to connectrpc.com/connect/v2.
protoc-gen-connect-go command
protoc-gen-connect-go is a plugin for the Protobuf compiler that generates Go code.
 protoc-gen-connect-go is a plugin for the Protobuf compiler that generates Go code.
Package connectgzip provides a gzip connect.Compressor for the "gzip" Content-Encoding.
 Package connectgzip provides a gzip connect.Compressor for the "gzip" Content-Encoding.
Package connecthttp adapts connect onto net/http.
 Package connecthttp adapts connect onto net/http.
Package connectinprocess provides an in-process connect.Transport.
 Package connectinprocess provides an in-process connect.Transport.
Package connectproto provides protobuf codecs for connect.
 Package connectproto provides protobuf codecs for connect.
internal
assert
Package assert is a minimal assert package using generics.
 Package assert is a minimal assert package using generics.
bufferpool
Package bufferpool provides a pool of reusable byte buffers shared by the codecs and transport.
 Package bufferpool provides a pool of reusable byte buffers shared by the codecs and transport.
gen/connect/collide/v1
gen/connect/collide/v1/collidev1connect
gen/connect/import/v1
gen/connect/import/v1/importv1connect
gen/connect/ping/v1
gen/connect/ping/v1/pingv1connect
The connect.ping.v1 package contains an echo service designed to test the connect-go implementation.
 The connect.ping.v1 package contains an echo service designed to test the connect-go implementation.
memhttp
memhttp/memhttptest

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.