diff --git a/AGENTS.md b/AGENTS.md index 5bac156..d01e2a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,9 @@ architecture. - `health` owns HTTP liveness/readiness behavior and dependency checks. - `observability` owns opt-in request correlation and log enrichment, not sinks or product telemetry policy. -- `rpc` owns Connect unary server error normalization, not domain classification. +- `rpc` owns Connect v1 unary server error normalization, not domain classification. + It is deprecated; remove it in the next major release. +- `rpc/connectv2` owns the same normalization for Connect v2 servers. - `service` owns process-serving and graceful-shutdown behavior. - `cmd/example` demonstrates composition and may depend on every public package. - Public library packages must not depend on `cmd`, examples, or a consumer. diff --git a/README.md b/README.md index 9671bae..b975df9 100644 --- a/README.md +++ b/README.md @@ -29,11 +29,12 @@ debug information for development. | [`database`](./database) | Bounded SQL startup, pool configuration, and readiness checks | | [`health`](./health) | Liveness and readiness probes with bounded dependency checks | | [`observability`](./observability) | Trusted-proxy-aware request IDs and context-aware log correlation | -| [`rpc`](./rpc) | Safe Connect unary server error boundaries | +| [`rpc`](./rpc) | Deprecated: safe Connect v1 unary server error boundaries | +| [`rpc/connectv2`](./rpc/connectv2) | Safe Connect v2 server error boundaries | | [`service`](./service) | HTTP serving, graceful shutdown, and post-drain resource cleanup | The foundations cover process lifecycle, health, driver-neutral SQL pools, -request/log correlation, and unary RPC error boundaries. Further RPC conventions, queries, authentication mechanisms, shared +request/log correlation, and RPC error boundaries for Connect v1 and v2. Further RPC conventions, queries, authentication mechanisms, shared contracts, and test infrastructure will be extracted only when a real consumer gives us a concrete API to design. diff --git a/docs/architecture.md b/docs/architecture.md index 905fff5..967e25e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -17,6 +17,7 @@ database health observability service └──────────┴────────────┴─────────────┴── Go standard library rpc ── Connect ── Protobuf +rpc/connectv2 ── Connect v2 ── Protobuf ``` `database`, `health`, `observability`, and `service` are independent foundations. The example application @@ -29,6 +30,12 @@ and interceptors directly rather than introducing a parallel status abstraction. The other foundations retain their standard-library-only imports. Consumers that do not import `rpc` do not link Connect into their binaries. +`rpc/connectv2` is the same boundary for `connectrpc.com/connect/v2`, a separate +module path with a stream-based server API. It does not import `rpc`; the shared +rules are duplicated deliberately so neither Connect major version links the +other. Keeping both preserves the v1 API for existing consumers; `rpc` is +deprecated and will be removed in the next major release. + The concrete extraction is a unary error boundary: repeated transport handlers were wrapping unexpected storage and authorization-check failures with raw error messages. Normalization removes internal diagnostics while leaving domain status diff --git a/go.mod b/go.mod index dfe2dd5..5a9f377 100644 --- a/go.mod +++ b/go.mod @@ -4,5 +4,6 @@ go 1.27.0 require ( connectrpc.com/connect v1.21.1 + connectrpc.com/connect/v2 v2.0.2 google.golang.org/protobuf v1.36.12 ) diff --git a/go.sum b/go.sum index 459a23f..a1d9f5b 100644 --- a/go.sum +++ b/go.sum @@ -1,5 +1,7 @@ connectrpc.com/connect v1.21.1 h1:h2kacdlzXpZU2OQFSv98xkjYXNUSr/ptxmGVbS/+CRM= connectrpc.com/connect v1.21.1/go.mod h1:fhMcVJ5w6r/yTYhnkEbW6+sIF7OZ5Ay7KYgmfebh2ek= +connectrpc.com/connect/v2 v2.0.2 h1:PoPDmOlhc46elsuCdKCKTxjNBb3HJlKF+s/sP2oucPw= +connectrpc.com/connect/v2 v2.0.2/go.mod h1:N32OLrstcPUzkykFynnefFro3+xzSdOrZlK2jHmS/xo= github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc= diff --git a/observability/rpc_test.go b/observability/rpc_test.go index 2630db5..a0599ea 100644 --- a/observability/rpc_test.go +++ b/observability/rpc_test.go @@ -6,13 +6,15 @@ import ( "encoding/json/v2" "errors" "log/slog" + "net/http" "net/http/httptest" "strings" "testing" - "connectrpc.com/connect" + "connectrpc.com/connect/v2" + "connectrpc.com/connect/v2/connecthttp" "github.com/fuf-stack/hardcore/observability" - "github.com/fuf-stack/hardcore/rpc" + "github.com/fuf-stack/hardcore/rpc/connectv2" "google.golang.org/protobuf/types/known/emptypb" ) @@ -20,36 +22,42 @@ import ( func TestConnectErrorCorrelation(t *testing.T) { var output bytes.Buffer logger := slog.New(observability.NewLogHandler(slog.NewJSONHandler(&output, nil))) - logErrors := connect.UnaryInterceptorFunc(func(next connect.UnaryFunc) connect.UnaryFunc { - return func(ctx context.Context, req connect.AnyRequest) (connect.AnyResponse, error) { - res, err := next(ctx, req) + logErrors := func(next connect.ServerFunc) connect.ServerFunc { + return func(ctx context.Context, spec connect.Spec, stream connect.ServerStream) error { + err := next(ctx, spec, stream) if err != nil { // The application deliberately selects a safe diagnostic, not raw error text. logger.ErrorContext(ctx, "operation failed", "error_class", "internal") } - return res, err + return err } - }) + } correlate, err := observability.NewRequestIDMiddleware() if err != nil { t.Fatal(err) } - handler := connect.NewUnaryHandler("/example.v1.Service/Call", - func(context.Context, *connect.Request[emptypb.Empty]) (*connect.Response[emptypb.Empty], error) { - return nil, errors.New("private backend detail") - }, connect.WithInterceptors(rpc.UnaryErrorInterceptor(), logErrors)) - server := httptest.NewServer(correlate(handler)) - defer server.Close() - client := connect.NewClient[emptypb.Empty, emptypb.Empty](server.Client(), server.URL+"/example.v1.Service/Call") - _, err = client.CallUnary(t.Context(), connect.NewRequest(&emptypb.Empty{})) + spec := connect.Spec{StreamType: connect.StreamTypeUnary, Procedure: "/example.v1.Service/Call"} + server := connect.NewServer(connectv2.ServerErrorInterceptor(), logErrors) + server.Register(connect.Method{Spec: spec, Handler: func(_ context.Context, _ connect.Spec, stream connect.ServerStream) error { + if err := stream.Receive(&emptypb.Empty{}); err != nil { + return err + } + return errors.New("private backend detail") + }}) + mux := http.NewServeMux() + connecthttp.Mount(mux, server) + httpServer := httptest.NewServer(correlate(mux)) + defer httpServer.Close() + client := connect.NewClient(connecthttp.NewTransport(httpServer.Client(), httpServer.URL)) + ctx, info := connect.NewClientContext(t.Context()) + err = client.CallUnary(ctx, spec, &emptypb.Empty{}, &emptypb.Empty{}) if connect.CodeOf(err) != connect.CodeInternal || strings.Contains(err.Error(), "private") { t.Fatalf("unexpected wire error: %v", err) } - wire, ok := errors.AsType[*connect.Error](err) - if !ok { + if _, ok := errors.AsType[*connect.Error](err); !ok { t.Fatal("missing Connect error") } - id := wire.Meta().Get(observability.RequestIDHeader) + id := info.ResponseHeader().Get(observability.RequestIDHeader) lines := strings.Split(strings.TrimSpace(output.String()), "\n") if len(lines) != 1 { t.Fatalf("log count = %d; want 1", len(lines)) diff --git a/rpc/README.md b/rpc/README.md index 88befe9..01dbdae 100644 --- a/rpc/README.md +++ b/rpc/README.md @@ -1,5 +1,9 @@ # RPC error boundaries +> **Deprecated:** this package targets Connect v1. New servers should use +> [`rpc/connectv2`](./connectv2) with `connectrpc.com/connect/v2`. This package +> will be removed in the next major release. + `rpc` provides `NormalizeError` and `UnaryErrorInterceptor` for Connect unary servers. It contains no service contracts, domain error mappings, or access policy. diff --git a/rpc/connectv2/README.md b/rpc/connectv2/README.md new file mode 100644 index 0000000..aab746e --- /dev/null +++ b/rpc/connectv2/README.md @@ -0,0 +1,47 @@ +# Connect v2 error boundaries + +`connectv2` provides `NormalizeError` and `ServerErrorInterceptor` for servers +built on `connectrpc.com/connect/v2`. It is the Connect v2 counterpart of +[`rpc`](..), which keeps serving Connect v1. It contains no service contracts, +domain error mappings, or access policy. + +```go +server := connect.NewServer(connectv2.ServerErrorInterceptor(), logging) +examplev1connect.RegisterEchoServiceHandler(server, echo) +connecthttp.Mount(mux, server) +``` + +Pass the interceptor first (outermost). Inner logging interceptors can record +the original error before normalization. Nothing is logged automatically. + +- Cancellation and deadline errors receive their corresponding Connect codes. +- Explicit local Connect errors are trusted public responses; their wrapper + text is removed, but their messages and details are otherwise preserved. +- Internal and unknown Connect errors are exceptions: only their code survives, + with the public message `internal error` and no details or cause. +- Remote Connect errors, a peer's verdict returned unchanged by the handler, + become internal errors without the peer's code, message, or details. +- Unclassified errors become internal errors without exposing their cause. + +## Differences from `rpc` + +Connect v2 server interceptors surround the whole call, so the boundary covers +unary and streaming RPCs alike. On streams it replaces only the final error; +messages already sent are unaffected. Connect v2 errors carry no metadata, so +response headers and trailers set by handlers pass through unchanged. Remote +errors are handled explicitly because v2 marks them; `rpc` has no such signal. + +An explicit Connect status takes precedence over wrapped context errors. For +joined context errors without an explicit status, deadline takes precedence. +Applications must supply safe public messages and details for other explicit +status codes; wrapping a database failure as unavailable does **not** make its +text safe. + +Domain classification stays in the application. Return a safe Connect error for +expected failures and an ordinary error for unexpected failures. There are no +settings or environment variables. Do not use this boundary on clients. + +Panic recovery, HTTP middleware errors, and protocol-level errors raised before +the interceptor chain runs are not covered. Test the complete application's HTTP +boundary separately. Run `make check` for unit and real HTTP round-trip tests of +unary and server-streaming calls. diff --git a/rpc/connectv2/errors.go b/rpc/connectv2/errors.go new file mode 100644 index 0000000..5037d29 --- /dev/null +++ b/rpc/connectv2/errors.go @@ -0,0 +1,60 @@ +// Package connectv2 provides product-neutral Connect v2 server error boundaries. +// It mirrors package rpc, which targets Connect v1, for servers built on +// connectrpc.com/connect/v2. +package connectv2 + +import ( + "context" + "errors" + + "connectrpc.com/connect/v2" +) + +// internalMessage is the only public message for redacted failures. +const internalMessage = "internal error" + +// NormalizeError prepares a handler error for public transport. Nil stays nil. +// Explicit local Connect errors are trusted public responses, except Internal +// and Unknown: their messages, details, and causes are discarded. Remote errors, +// a peer's verdict returned unchanged by the handler, become Internal without +// their code, message, or details. Wrapped Connect errors retain only the +// underlying Connect error, not wrapper text. Otherwise context errors receive +// stable codes and all other errors become Internal. The original error is not +// retained; log it before this boundary. Consumers remain responsible for safe +// messages and details on other explicit status codes. +func NormalizeError(err error) error { + if err == nil { + return nil + } + if wire, ok := errors.AsType[*connect.Error](err); ok && wire != nil { + switch { + case wire.IsRemote(): + return connect.NewError(connect.CodeInternal, internalMessage) + case wire.Code() == connect.CodeInternal, wire.Code() == connect.CodeUnknown: + return connect.NewError(wire.Code(), internalMessage) + default: + return wire + } + } + if errors.Is(err, context.DeadlineExceeded) { + return connect.NewError(connect.CodeDeadlineExceeded, context.DeadlineExceeded.Error()) + } + if errors.Is(err, context.Canceled) { + return connect.NewError(connect.CodeCanceled, context.Canceled.Error()) + } + return connect.NewError(connect.CodeInternal, internalMessage) +} + +// ServerErrorInterceptor normalizes the error that ends any server RPC, unary +// or streaming. Pass it first to connect.NewServer so it surrounds the other +// interceptors; inner logging can observe the original error. Messages already +// sent on a stream are not affected. It does not recover panics or cover HTTP +// middleware or protocol errors raised before the interceptor chain runs. +// Do not use it on clients: it deliberately discards diagnostic information. +func ServerErrorInterceptor() connect.ServerInterceptor { + return func(next connect.ServerFunc) connect.ServerFunc { + return func(ctx context.Context, spec connect.Spec, stream connect.ServerStream) error { + return NormalizeError(next(ctx, spec, stream)) + } + } +} diff --git a/rpc/connectv2/errors_test.go b/rpc/connectv2/errors_test.go new file mode 100644 index 0000000..eed33e7 --- /dev/null +++ b/rpc/connectv2/errors_test.go @@ -0,0 +1,228 @@ +package connectv2_test + +import ( + "context" + "errors" + "fmt" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "connectrpc.com/connect/v2" + "connectrpc.com/connect/v2/connecthttp" + "connectrpc.com/connect/v2/connectproto" + "github.com/fuf-stack/hardcore/rpc/connectv2" + "google.golang.org/protobuf/types/known/emptypb" + "google.golang.org/protobuf/types/known/wrapperspb" +) + +// privateDetail returns an error detail that must never reach a client. +func privateDetail(t *testing.T) *connect.ErrorDetail { + t.Helper() + detail, err := connectproto.NewErrorDetail(wrapperspb.String("private detail")) + if err != nil { + t.Fatal(err) + } + return detail +} + +// TestNormalizeError covers classification, precedence, and diagnostic redaction. +func TestNormalizeError(t *testing.T) { + private := errors.New("private storage failure") + public := connect.NewError(connect.CodeInvalidArgument, "invalid input") + tests := []struct { + name string + err error + code connect.Code + message string + }{ + // Wrapped cancellations must not disclose wrapper diagnostics. + {"canceled", fmt.Errorf("private: %w", context.Canceled), connect.CodeCanceled, "context canceled"}, + // Deadlines take precedence when both context sentinels are joined. + {"deadline", errors.Join(context.Canceled, context.DeadlineExceeded), connect.CodeDeadlineExceeded, "context deadline exceeded"}, + // An explicitly mapped status takes precedence over its underlying cause. + {"explicit", connect.NewError(connect.CodeUnavailable, "try again").WithCause(context.Canceled), connect.CodeUnavailable, "try again"}, + // Explicit internal errors must not bypass redaction. + {"internal", connect.NewError(connect.CodeInternal, "private").WithCause(private), connect.CodeInternal, "internal error"}, + // Raw unexpected failures receive a safe internal status. + {"ordinary", private, connect.CodeInternal, "internal error"}, + // A peer's verdict is not the handler's own and must not be forwarded. + {"remote", connect.NewError(connect.CodeNotFound, "private upstream").WithRemote(), connect.CodeInternal, "internal error"}, + // Wrapped remote verdicts are redacted the same way. + {"remote wrapped", fmt.Errorf("private: %w", connect.NewError(connect.CodePermissionDenied, "private upstream").WithRemote()), connect.CodeInternal, "internal error"}, + // Unknown remains unknown but cannot expose its original message. + {"unknown", connect.NewError(connect.CodeUnknown, "private").WithCause(private), connect.CodeUnknown, "internal error"}, + // Wrappers around expected public errors stay private. + {"wrapped", fmt.Errorf("private: %w", public), connect.CodeInvalidArgument, "invalid input"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := connectv2.NormalizeError(tt.err) + wire, ok := errors.AsType[*connect.Error](got) + if !ok || wire.Code() != tt.code || wire.Message() != tt.message { + t.Fatalf("NormalizeError = %v; want %v: %s", got, tt.code, tt.message) + } + if errors.Is(got, private) || strings.Contains(got.Error(), "private") || wire.IsRemote() { + t.Fatalf("private diagnostics retained: %v", got) + } + }) + } + if connectv2.NormalizeError(nil) != nil { + t.Fatal("nil changed") + } +} + +// TestNormalizeErrorDetails preserves trusted responses but strips internal data. +func TestNormalizeErrorDetails(t *testing.T) { + detail := privateDetail(t) + for _, tc := range []struct { + name string + err *connect.Error + trusted bool + }{ + {"internal", connect.NewError(connect.CodeInternal, "message"), false}, + {"invalid argument", connect.NewError(connect.CodeInvalidArgument, "message"), true}, + {"remote", connect.NewError(connect.CodeInvalidArgument, "message").WithRemote(), false}, + {"unknown", connect.NewError(connect.CodeUnknown, "message"), false}, + } { + t.Run(tc.name, func(t *testing.T) { + original := tc.err.WithDetail(detail).WithCause(errors.New("cause")) + got, ok := errors.AsType[*connect.Error](connectv2.NormalizeError(original)) + if !ok { + t.Fatal("not a Connect error") + } + if tc.trusted { + if got != original { + t.Fatal("trusted error replaced") + } + } else if len(got.Details()) != 0 || got.Unwrap() != nil { + t.Fatal("internal details or cause retained") + } + if len(original.Details()) != 1 || original.Unwrap() == nil { + t.Fatal("original mutated") + } + }) + } +} + +// TestServerErrorInterceptorSuccess ensures inputs and nil errors pass unchanged. +func TestServerErrorInterceptorSuccess(t *testing.T) { + spec := connect.Spec{Procedure: "/example.v1.EchoService/Echo"} + ctx := t.Context() + called := false + handler := connectv2.ServerErrorInterceptor()(func(gotCtx context.Context, gotSpec connect.Spec, stream connect.ServerStream) error { + called = true + if gotCtx != ctx || gotSpec != spec || stream != nil { + t.Fatal("input changed") + } + return nil + }) + if err := handler(ctx, spec, nil); err != nil || !called { + t.Fatalf("handler = %v, called %v", err, called) + } +} + +// echoProcedure and streamProcedure are neutral test procedures. +const ( + echoProcedure = "/example.v1.EchoService/Echo" + streamProcedure = "/example.v1.EchoService/Watch" +) + +// newServer serves a unary and a server-streaming method over real HTTP. Both +// fail with handlerErr; the streaming method first sends one message. The +// logging interceptor records the error it observes inside the boundary. +func newServer(t *testing.T, handlerErr error, observed *[]error) (*connect.Client, connect.Spec, connect.Spec) { + t.Helper() + unary := connect.Spec{StreamType: connect.StreamTypeUnary, Procedure: echoProcedure} + streaming := connect.Spec{StreamType: connect.StreamTypeServer, Procedure: streamProcedure} + logging := func(next connect.ServerFunc) connect.ServerFunc { + return func(ctx context.Context, spec connect.Spec, stream connect.ServerStream) error { + err := next(ctx, spec, stream) + *observed = append(*observed, err) + return err + } + } + server := connect.NewServer(connectv2.ServerErrorInterceptor(), logging) + server.Register( + connect.Method{Spec: unary, Handler: func(_ context.Context, _ connect.Spec, stream connect.ServerStream) error { + if err := stream.Receive(&emptypb.Empty{}); err != nil { + return err + } + return handlerErr + }}, + connect.Method{Spec: streaming, Handler: func(_ context.Context, _ connect.Spec, stream connect.ServerStream) error { + if err := stream.Receive(&emptypb.Empty{}); err != nil { + return err + } + if err := stream.Send(wrapperspb.String("public")); err != nil { + return err + } + return handlerErr + }}, + ) + mux := http.NewServeMux() + connecthttp.Mount(mux, server) + httpServer := httptest.NewServer(mux) + t.Cleanup(httpServer.Close) + return connect.NewClient(connecthttp.NewTransport(httpServer.Client(), httpServer.URL)), unary, streaming +} + +// TestServerErrorInterceptorWire verifies safe errors over actual HTTP transport +// for unary and server-streaming RPCs, after inner interceptors saw the original. +func TestServerErrorInterceptorWire(t *testing.T) { + private := errors.New("private database credentials") + for _, tc := range []struct { + name string + err error + code connect.Code + message string + details int + }{ + {"internal", connect.NewError(connect.CodeInternal, "private").WithDetail(privateDetail(t)).WithCause(private), connect.CodeInternal, "internal error", 0}, + {"ordinary", private, connect.CodeInternal, "internal error", 0}, + {"remote", connect.NewError(connect.CodeNotFound, "private upstream").WithRemote(), connect.CodeInternal, "internal error", 0}, + // Safe explicit limits stay visible to clients with their public detail. + {"resource exhausted", fmt.Errorf("private: %w", connect.NewError(connect.CodeResourceExhausted, "too many items").WithDetail(privateDetail(t))), connect.CodeResourceExhausted, "too many items", 1}, + } { + t.Run(tc.name, func(t *testing.T) { + var observed []error + client, unary, streaming := newServer(t, tc.err, &observed) + check := func(err error) { + t.Helper() + wire, ok := errors.AsType[*connect.Error](err) + if !ok || wire.Code() != tc.code || wire.Message() != tc.message || len(wire.Details()) != tc.details { + t.Fatalf("wire error = %v (%d details); want %v: %s", err, len(wire.Details()), tc.code, tc.message) + } + if tc.details == 0 && strings.Contains(err.Error(), "private") { + t.Fatalf("private diagnostics on the wire: %v", err) + } + } + check(client.CallUnary(t.Context(), unary, &emptypb.Empty{}, &emptypb.Empty{})) + + stream, err := client.CallServerStream(t.Context(), streaming, &emptypb.Empty{}) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = stream.Close() }) + msg := &wrapperspb.StringValue{} + if err := stream.Receive(msg); err != nil || msg.GetValue() != "public" { + t.Fatalf("first message = %v, %v", msg, err) + } + check(stream.Receive(msg)) + + if len(observed) != 2 || observed[0] != tc.err || observed[1] != tc.err { + t.Fatalf("logging interceptor observed %v; want the original error twice", observed) + } + }) + } +} + +// TestServerErrorInterceptorWireSuccess keeps successful RPCs unchanged on the wire. +func TestServerErrorInterceptorWireSuccess(t *testing.T) { + var observed []error + client, unary, _ := newServer(t, nil, &observed) + if err := client.CallUnary(t.Context(), unary, &emptypb.Empty{}, &emptypb.Empty{}); err != nil { + t.Fatal(err) + } +} diff --git a/rpc/errors.go b/rpc/errors.go index 76dbf34..91541ed 100644 --- a/rpc/errors.go +++ b/rpc/errors.go @@ -1,4 +1,8 @@ -// Package rpc provides product-neutral Connect server error boundaries. +// Package rpc provides product-neutral Connect v1 server error boundaries. +// +// Deprecated: Use package github.com/fuf-stack/hardcore/rpc/connectv2 with +// connectrpc.com/connect/v2. This package will be removed in the next major +// release. package rpc import (