From b81a8d7664469f3922fcb00dad41eb8186c06946 Mon Sep 17 00:00:00 2001 From: Josue Giron Date: Sat, 21 Nov 2026 18:24:40 +0000 Subject: [PATCH] feat(api)!: log the default instance through slog.Default Second part of the owner decision (2026-11-21) that the default instance behaves like api.New(). The default instance now writes the same slog records as an instance with WithLogger, through slog.Default() read at call time; an api.New() without WithLogger still logs nothing. The last fromNew forks (logging, the response writer) are gone, so the default instance and instances share one code path. The v0 golden log test is replaced by golden slog records in default_instance_test.go. Deprecated: LogRequestBody, LogResponseBody, PrintFullEvent and MaxLoggedBodyBytes (they affect only the deprecated Log* functions). PrintError and Fatal are documented as ignored. TraceVisibility, TraceIDLength and BlankSuccess keep configuring the default instance and stay undeprecated (no replacement option). BREAKING CHANGE: for programs that use the package-level API without api.New (the default instance): - ProcessRequest, the body middlewares, the Get*Value* helpers and the response writer log slog records (request, response, request body rejected, panic recovered, ...) through slog.Default() instead of REQUEST/RESPONSE lines through Print and PrintError; - the package no longer calls PrintError (or Fatal); Print is called only by the deprecated LogRequest/LogResponse*. A program that assigned api.PrintError or api.Print to route logs must call slog.SetDefault or move to api.New(api.WithLogger(...)); - request and response bodies and the parsed form are never logged, even with LogRequestBody or LogResponseBody set; - SensitiveLogKeys adds keys to the built-in list and can no longer remove a built-in key; - a type that embeds ResponseWriter logs through slog.Default. Stay on v0.11.x to keep v0 behavior. Co-Authored-By: Claude Opus 5.5 --- README.md | 17 +- default_instance_test.go | 303 +++++++++++++++++++++++++++++++++--- default_log_golden_test.go | 159 ------------------- doc.go | 6 +- docs/legacy.md | 2 +- docs/migration-v1.md | 45 +++--- example_migration_test.go | 2 +- functions.go | 55 ++++--- functions_logging_test.go | 39 ++--- instance.go | 29 ++-- instance_bench_test.go | 15 +- instance_log.go | 135 ++++++++-------- instance_log_test.go | 31 +--- middlewares.go | 2 +- middlewares_recover_test.go | 8 +- response.go | 92 +---------- response_writer_test.go | 60 +++---- 17 files changed, 503 insertions(+), 497 deletions(-) delete mode 100644 default_log_golden_test.go diff --git a/README.md b/README.md index f70f323..7940905 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ func main() { 2. **`api.ProcessRequest`.** Wrap a handler with this middleware to get the full flow. It: - reads the body and parses it according to the [request mode](#request-and-response-modes); an invalid JSON body answers 400 with code `E002`, and a body over 10 MiB answers 413 (see [Security notes](#security-notes)); - collects request metadata from HTTP headers (see [Reading the request](#reading-the-request)); - - assigns an [event ID](#trace-ids) and logs the request and the response (on an `api.New` instance only through its `api.WithLogger` logger, and nothing without one; see [Logging](#logging)); + - assigns an [event ID](#trace-ids) and logs the request and the response (on an `api.New` instance only through its `api.WithLogger` logger, and nothing without one; on the default instance through `slog.Default`; see [Logging](#logging)); - stores the request context, replaces `r.Body` with the endpoint content, and answers 500 if the handler panics. Use `api.MiddlewaresChain(...)` to compose it with your own middlewares. `api.AddSkipPath(api.GenSkipPath(method, path), true)` makes it pass a route through untouched. @@ -113,7 +113,7 @@ a := api.New( http.ListenAndServe(":8080", a.Handler(router)) ``` -`a.Handler` stores the instance in the request context, so `api.ProcessRequest`, `api.RequestBody`, the token middlewares, `Write(w, r)` on every response type (`api.Success`, `api.Error`, `api.Warning`, `api.Informative`) and `api.WriteError` use its modes; handler code does not change. Wrap the outermost chain: middlewares outside `a.Handler` (and the package-level `api.Write(data, w)`, which takes no request) use the default instance, so their rejections use the package modes and loggers instead of the instance's options; with nested instances the innermost one wins. An instance is immutable after `api.New`, and two instances in one process (two services, or two tests) do not see each other's modes. `api.New()` with no options parses plain requests and writes envelope responses. An instance, like the default instance, sends response codes as declared (`PLN-001`); `api.WithLowercaseCodes()` restores v0's lowercasing. An instance uses the built-in request receiver, response formatter and response writer unless you pass your own: +`a.Handler` stores the instance in the request context, so `api.ProcessRequest`, `api.RequestBody`, the token middlewares, `Write(w, r)` on every response type (`api.Success`, `api.Error`, `api.Warning`, `api.Informative`) and `api.WriteError` use its modes; handler code does not change. Wrap the outermost chain: middlewares outside `a.Handler` (and the package-level `api.Write(data, w)`, which takes no request) use the default instance, so their rejections use the package modes and `slog.Default` instead of the instance's options; with nested instances the innermost one wins. An instance is immutable after `api.New`, and two instances in one process (two services, or two tests) do not see each other's modes. `api.New()` with no options parses plain requests and writes envelope responses. An instance, like the default instance, sends response codes as declared (`PLN-001`); `api.WithLowercaseCodes()` restores v0's lowercasing. An instance uses the built-in request receiver, response formatter and response writer unless you pass your own: ```go a := api.New( @@ -143,7 +143,7 @@ An unknown value falls back to the default (`api.RequestModePlain`, `api.Respons `api.ResponseModeProblem` applies to the built-in formatter, set with `api.WithResponseMode` or, on the default instance, the deprecated `api.SetResponseMode` (since v1.0.0; v0 fell back to envelope). In a problem body `title` is the HTTP status phrase (`Not Found`) when the response title is empty or a library default (`Error response!`, `Sorry!`, `Unauthorized!`, the helpers' titles), and the title the service set otherwise (the check is by text: a service title equal to a library default also becomes the status phrase, and a default reassigned through `api.DefaultErrorTitle` and its siblings is kept); `detail` is the public message without the trace suffix, and `code` and `event_id` are extension members; `type` is always `about:blank`, and content, token, actions and info are not sent. The built-in response writer sends `Content-Type: application/json` unless the response `Headers` set a non-empty `Content-Type`, which always wins, in every mode (one set on `w.Header()` by the handler does not count) (a fix: v0 discarded a `Content-Type` the service set); the 500 sent for a body that cannot be encoded, by the default instance or an instance, carries the error body's `Content-Type` and drops the failed body's other headers (`Content-Encoding`, `Content-Length`, `ETag`, …). -Requests that are not wrapped by an instance's `Handler` use the default instance. Since v1.0.0 it behaves like `api.New()` with its defaults (codes as declared, no token echo, 10 MiB body limit); it reads the package variables `api.CurrentRequestMode` and `api.CurrentResponseMode` (set with `api.SetRequestMode` and `api.SetResponseMode`). These four names are deprecated: they affect only the default instance, for the whole process. [docs/migration-v1.md](docs/migration-v1.md) lists every deprecated name with its option. The `envelope` package types are for OpenAPI documentation and match the envelope response mode. +Requests that are not wrapped by an instance's `Handler` use the default instance. Since v1.0.0 it behaves like `api.New()` with its defaults (codes as declared, no token echo, 10 MiB body limit, `slog` records through `slog.Default`); it reads the package variables `api.CurrentRequestMode` and `api.CurrentResponseMode` (set with `api.SetRequestMode` and `api.SetResponseMode`). These four names are deprecated: they affect only the default instance, for the whole process. [docs/migration-v1.md](docs/migration-v1.md) lists every deprecated name with its option. The `envelope` package types are for OpenAPI documentation and match the envelope response mode. ## Reading the request @@ -250,7 +250,7 @@ a := api.New( ) ``` -Kinds without an override keep `api.StatusForKind`. Only statuses 400–599 are accepted: other calls are ignored and leave any earlier override for the kind in place, and a later valid call wins. Errors without a kind always answer 500. The title follows the decided status: the internal title for any 5xx, the unauthorized title for 401 and 403. The hook runs on the request goroutine with the original error and the status `WriteError` decided (a handler that already wrote a header, or a custom formatter or writer, can send another), before anything is written; it is shared by all requests the instance serves and may run concurrently, so it must be safe for concurrent use. A panic in it is not recovered: `api.ProcessRequest` answers 500 and logs it through the instance's `api.WithLogger` logger with the panic value (nothing is logged without a logger), and without `api.ProcessRequest` `net/http` aborts the connection. On the default instance the `api.PrintError` line shows the panic value (since v0.11.0). Only `WriteError` calls the hook: not `Error400`/`Error500`/the other helpers, and not the library's own rejections (body-parse failures in `api.RequestBody`/`api.ProcessRequest`, the token middlewares' 401s, `api.ProcessRequest`'s panic 500). The default instance has no overrides and no hook. `ExampleWithKindStatus` and `ExampleWithErrorHook` are the compiled versions. +Kinds without an override keep `api.StatusForKind`. Only statuses 400–599 are accepted: other calls are ignored and leave any earlier override for the kind in place, and a later valid call wins. Errors without a kind always answer 500. The title follows the decided status: the internal title for any 5xx, the unauthorized title for 401 and 403. The hook runs on the request goroutine with the original error and the status `WriteError` decided (a handler that already wrote a header, or a custom formatter or writer, can send another), before anything is written; it is shared by all requests the instance serves and may run concurrently, so it must be safe for concurrent use. A panic in it is not recovered: `api.ProcessRequest` answers 500 and logs it through the instance's `api.WithLogger` logger with the panic value (nothing is logged without a logger), and without `api.ProcessRequest` `net/http` aborts the connection. On the default instance the panic is logged the same way through `slog.Default`. Only `WriteError` calls the hook: not `Error400`/`Error500`/the other helpers, and not the library's own rejections (body-parse failures in `api.RequestBody`/`api.ProcessRequest`, the token middlewares' 401s, `api.ProcessRequest`'s panic 500). The default instance has no overrides and no hook. `ExampleWithKindStatus` and `ExampleWithErrorHook` are the compiled versions. ## Logging @@ -264,9 +264,9 @@ a := api.New( // {"level":"INFO","msg":"request","event_id":"…","method":"GET","uri":"/login?access_token=[REDACTED]&page=2","headers":{"Pin":["[REDACTED]"]}} ``` -`api.ProcessRequest` writes a `request` record (`event_id`, `method`, `uri`, `headers`) and a `response` record (`event_id`, `method`, `uri`, `status`, `status_text`, `duration_ms`) at info level. A rejected body, a failed `Get*Value*`/`UnmarshalBody` helper, a recovered panic (`panic recovered`, with the panic value) and a response that cannot be encoded are error records with an `error` or `panic` attribute; a panic with `http.ErrAbortHandler` is a `handler aborted` debug record. A failed `Get*Value*` helper adds the name as `key`; for a sensitive name its `error` is only the kind (`invalid syntax`, `value out of range`, `invalid value`), never the value. A response that cannot be encoded (for example a `NaN` in the content) is answered with the `Error500()` body instead; the writer gets no request, so its records carry no request context or `event_id`. Bodies and the parsed form are never logged (query values appear only in `uri`). Header values, query values in `uri` and the user information of the `uri` are masked with the same rules as the default instance (see [Security notes](#security-notes)); secrets in path segments are not masked. The sensitive keys are the default list (`authorization`, `token`, `password`, `secret`, `credential`, `apikey`, `api-key`, `key`, `cookie`, `session`) plus the keys of `api.WithSensitiveLogKeys`, which can only add. `ExampleWithLogger` is the compiled version. +`api.ProcessRequest` writes a `request` record (`event_id`, `method`, `uri`, `headers`) and a `response` record (`event_id`, `method`, `uri`, `status`, `status_text`, `duration_ms`) at info level. A rejected body, a failed `Get*Value*`/`UnmarshalBody` helper, a recovered panic (`panic recovered`, with the panic value) and a response that cannot be encoded are error records with an `error` or `panic` attribute; a panic with `http.ErrAbortHandler` is a `handler aborted` debug record. A failed `Get*Value*` helper adds the name as `key`; for a sensitive name its `error` is only the kind (`invalid syntax`, `value out of range`, `invalid value`), never the value. A response that cannot be encoded (for example a `NaN` in the content) is answered with the `Error500()` body instead; the writer gets no request, so its records carry no request context or `event_id`. Bodies and the parsed form are never logged (query values appear only in `uri`). Header values, query values in `uri` and the user information of the `uri` are masked (see [Security notes](#security-notes)); secrets in path segments are not masked. The sensitive keys are the default list (`authorization`, `token`, `password`, `secret`, `credential`, `apikey`, `api-key`, `key`, `cookie`, `session`) plus the keys of `api.WithSensitiveLogKeys`, which can only add. `ExampleWithLogger` is the compiled version. -The default instance keeps v0.11.0: lines through `api.Print`/`api.PrintError` (the standard `log` package), `api.SensitiveLogKeys` with its masking rules (see [Security notes](#security-notes)), and the body-logging variables below. Neither calls `api.Fatal`: a response that cannot be encoded is answered with 500. `api.Print`, `api.PrintError`, `api.Fatal`, `api.SensitiveLogKeys`, `api.LogRequest`, `api.LogResponse` and `api.LogResponseWithDuration` are deprecated in favor of the options; `api.LogRequestBody`, `api.LogResponseBody`, `api.PrintFullEvent` and `api.MaxLoggedBodyBytes` are not deprecated and affect only the default instance. +Since v1.0.0 the default instance writes the same records through `slog.Default()`, read at call time (route them with `slog.SetDefault`). Its sensitive keys are the default list plus `api.SensitiveLogKeys`, which can add keys but no longer remove a default one. Neither calls `api.Fatal`: a response that cannot be encoded is answered with 500. The package no longer calls `api.Print` or `api.PrintError` (only the deprecated `api.LogRequest`, `api.LogResponse` and `api.LogResponseWithDuration` call `api.Print`). `api.Print`, `api.PrintError`, `api.Fatal`, `api.SensitiveLogKeys` and the `api.Log*` functions are deprecated in favor of the options; `api.LogRequestBody`, `api.LogResponseBody`, `api.PrintFullEvent` and `api.MaxLoggedBodyBytes` are deprecated too: they affect only the deprecated `api.Log*` functions, since bodies are never logged. ## Routing and OpenAPI @@ -364,9 +364,8 @@ See [ADR 0002](docs/adr/0002-stdadapter-servemux.md). - `doc.Security` and `docs.SetDefaultSecurity` only document authentication; they do not enforce it. Enforce it with a middleware: `api.CustomToken` (validated by `api.CustomTokenValidatorFunc`), `api.BasicToken` (validated by `api.ValidateBasicAuthCredentialsFunc`), or your own. - `api.BasicToken` with the default validator answers 401 to every request while `api.Username` or `api.Password` is empty or `"default"` (since v0.11.0; before, it accepted `default:default`). Set both, or replace `api.ValidateBasicAuthCredentialsFunc`, before exposing a route. The default validator compares credentials in constant time; a custom one should too (`crypto/subtle`). After a successful check, `BasicToken` copies the user name into the `Basic-Client` request header. Since v1.0.0 it no longer copies the plain password into a `Basic-Secret` header, and it removes a `Basic-Secret` header the client sent; a handler that needs the password must take it from its own credential source. - The request token is never echoed (since v1.0.0, on the default instance too): a response body carries a `token` only when the handler sets `SecurityToken` on the response, and `api.RequestHeaderSession` does not copy the `SecurityToken` request header into the response header; a handler that wants to return a token sets it itself. -- An `api.New` instance never logs bodies or the parsed form. It masks, by its sensitive keys (the `api.SensitiveLogKeys` defaults plus `api.WithSensitiveLogKeys`), header values and query parameter values in `uri`, and the user information of the `uri`, with the same rules as the default instance below. See [Logging](#logging). -- On the default instance, request and response bodies are logged only when `api.LogRequestBody` / `api.LogResponseBody` are true; values under the keys in `api.SensitiveLogKeys` are masked and bodies are cut at `api.MaxLoggedBodyBytes`. -- The default instance's request log masks, by the keys in `api.SensitiveLogKeys` (a name matches when it contains a key, ignoring case; the defaults include `authorization`, `token`, `password`, `key`, `cookie` and `session`): header values, JSON body fields, query parameter values in `uri` (names are found by splitting on `&` and `;`, and a masked value runs to the next `&`; a name that cannot be unescaped is masked too), and `form` values. It also masks the user information of an absolute-form, `//host` or CONNECT authority-form `uri` (`http://[REDACTED]@host/...`), up to the last `@`, so an `@` in the path or query hides the host and path too. Path segments are not masked. Masking is by name: a secret under a non-sensitive name (such as a URL with credentials in `?next=`) is logged as sent. A request body that is not JSON (form, XML, text) is logged as `[non-JSON body, N bytes]` unless `api.PrintFullEvent` is true. +- `api.ProcessRequest` never logs bodies or the parsed form. It masks, by its sensitive keys (a name matches when it contains a key, ignoring case; the defaults include `authorization`, `token`, `password`, `key`, `cookie` and `session`, plus `api.WithSensitiveLogKeys` on an instance or `api.SensitiveLogKeys` on the default instance): header values and query parameter values in `uri` (names are found by splitting on `&` and `;`, and a masked value runs to the next `&`; a name that cannot be unescaped is masked too). It also masks the user information of an absolute-form, `//host` or CONNECT authority-form `uri` (`http://[REDACTED]@host/...`), up to the last `@`, so an `@` in the path or query hides the host and path too. Path segments are not masked. Masking is by name: a secret under a non-sensitive name (such as a URL with credentials in `?next=`) is logged as sent. See [Logging](#logging). +- The deprecated `api.LogRequest`, `api.LogResponse` and `api.LogResponseWithDuration` log bodies only when `api.LogRequestBody` / `api.LogResponseBody` are true; they mask JSON body fields and `form` values by the keys in `api.SensitiveLogKeys` alone, cut bodies at `api.MaxLoggedBodyBytes`, and log a request body that is not JSON as `[non-JSON body, N bytes]` unless `api.PrintFullEvent` is true. - With `stdadapter`, a route variable can contain `/` and `..` (`/files/..%2F..%2Fetc` gives `name` = `../../etc`). Validate it before using it in a file path or another lookup that trusts it. - `api.ProcessRequest` stores the value of the `X-Forwarded-For` header up to its first `", "` as the `proxiedIPAddress` info value (and, when the request has no device UUID, as the event ID input). Only the first `X-Forwarded-For` header line is read. That value is set by the client: trust it only behind a proxy that overwrites the header, and do not use it on its own for rate limits, allow lists or audit. - An `api.New` instance bounds request bodies at 10 MiB: its `Handler` wraps the body in `http.MaxBytesReader`, and `api.ProcessRequest`, `api.RequestBody` and `api.UnmarshalBody` answer a larger body with 413 and code `E002` (title `Request content too large`). Set another limit with `api.WithMaxBodyBytes(n)`; `n <= 0` is ignored, so pass `math.MaxInt64` for no practical limit. Nested instance limits combine, so the smallest applies. A custom receiver or a handler that reads `r.Body` itself gets the `*http.MaxBytesError` and decides how to answer. `ExampleWithMaxBodyBytes` is the compiled version. diff --git a/default_instance_test.go b/default_instance_test.go index 946b9bb..13607bd 100644 --- a/default_instance_test.go +++ b/default_instance_test.go @@ -1,7 +1,11 @@ package api import ( + "bytes" + "encoding/json" stderrors "errors" + "log" + "log/slog" "maps" "math" "net/http" @@ -15,17 +19,20 @@ import ( "github.com/jgolang/errors/codes" ) -// countPackageErrorLogs replaces Print and PrintError with no-ops for one -// test and returns how many times PrintError was called. The default -// instance still logs through them until it moves to slog. -func countPackageErrorLogs(t *testing.T) *int { +// captureDefaultLogger makes slog.Default write JSON records into the +// returned buffer for one test. It also restores the standard logger's +// output and flags, which slog.SetDefault redirects. +func captureDefaultLogger(t *testing.T) *bytes.Buffer { t.Helper() - previousPrint, previousPrintError := Print, PrintError - calls := 0 - Print = func(string, ...interface{}) {} - PrintError = func(...interface{}) { calls++ } - t.Cleanup(func() { Print, PrintError = previousPrint, previousPrintError }) - return &calls + previous, previousOutput, previousFlags := slog.Default(), log.Writer(), log.Flags() + logger, buf := newRecordingLogger() + slog.SetDefault(logger) + t.Cleanup(func() { + slog.SetDefault(previous) + log.SetOutput(previousOutput) + log.SetFlags(previousFlags) + }) + return buf } // sameAsNewEventIDs matches what differs between two runs of one request: @@ -37,7 +44,7 @@ var sameAsNewEventIDs = regexp.MustCompile(`"event_id":"[0-9a-f]+"|\([0-9a-f]*-` // apart from event IDs. func TestDefaultInstanceAnswersLikeNew(t *testing.T) { usePackageModes(t, RequestModePlain, ResponseModeEnvelope) - countPackageErrorLogs(t) + captureDefaultLogger(t) declared := codes.New("PLN-001", "plan not found").WithKind(codes.KindNotFound) tests := []struct { name string @@ -99,7 +106,7 @@ func TestDefaultInstanceAnswersLikeNew(t *testing.T) { // instance in the same request mode. func TestDefaultInstanceInEnvelopeRequestModeAnswersLikeNew(t *testing.T) { usePackageModes(t, RequestModeEnvelope, ResponseModeEnvelope) - countPackageErrorLogs(t) + captureDefaultLogger(t) body := `{"header":{"token":"s3cr3t"},"content":{"title":"task"}}` handler := ProcessRequest(okHandler) @@ -187,23 +194,24 @@ func TestDefaultRequestHeaderSessionDoesNotCopyTheToken(t *testing.T) { func TestDefaultInstanceBoundsBodiesAtTheLibraryReadPoints(t *testing.T) { usePackageModes(t, RequestModePlain, ResponseModeEnvelope) - errorLogs := countPackageErrorLogs(t) + buf := captureDefaultLogger(t) tests := []struct { - name string - handler http.Handler + name string + handler http.Handler + wantLogged string }{ - {name: "ProcessRequest", handler: ProcessRequest(okHandler)}, - {name: "RequestBody", handler: RequestBody(okHandler)}, + {name: "ProcessRequest", handler: ProcessRequest(okHandler), wantLogged: "request body rejected"}, + {name: "RequestBody", handler: RequestBody(okHandler), wantLogged: "request body rejected"}, {name: "UnmarshalBody", handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { var payload map[string]any if response := UnmarshalBody(&payload, r); response != nil { response.Write(w, r) } - })}, + }), wantLogged: "request body not unmarshaled"}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - *errorLogs = 0 + buf.Reset() rec := serve(tt.handler, http.MethodPost, jsonBodyOfSize(defaultMaxBodyBytes+1), nil) @@ -213,9 +221,7 @@ func TestDefaultInstanceBoundsBodiesAtTheLibraryReadPoints(t *testing.T) { if title, code := envelopeHeader(t, rec.Body.Bytes()); title != "Request content too large" || code != string(ResponseCodes.InvalidJSON) { t.Fatalf("title, code = %q, %q, want the too-large title and %s", title, code, ResponseCodes.InvalidJSON) } - if *errorLogs != 1 { - t.Fatalf("PrintError called %d times, want 1", *errorLogs) - } + recordNamed(t, decodeRecords(t, buf), tt.wantLogged) }) } } @@ -264,3 +270,256 @@ func TestSetResponseModeProblemWritesProblemDetails(t *testing.T) { t.Fatalf("members = %v, want a 404 problem", members) } } + +// TestDefaultInstanceLogsThroughSlogDefault pins, as golden records, what the +// default ProcessRequest writes: request and response through slog.Default, with +// sensitive headers and query values masked and no body or form even when +// the deprecated body-logging flags are on. Print and PrintError are never +// called. +func TestDefaultInstanceLogsThroughSlogDefault(t *testing.T) { + failOnPackageLoggers(t) + previousLogRequestBody, previousLogResponseBody := LogRequestBody, LogResponseBody + LogRequestBody, LogResponseBody = true, true + t.Cleanup(func() { LogRequestBody, LogResponseBody = previousLogRequestBody, previousLogResponseBody }) + tests := []struct { + name string + body string + next http.HandlerFunc + parseForm bool + want []string + }{ + { + name: "success", + body: `{"title":"task","password":"bodysecret"}`, + want: []string{ + `{"event_id":"","headers":{"Authorization":["[REDACTED]"],"Cookie":["[REDACTED]"]},"level":"INFO","method":"POST","msg":"request","uri":"/tasks?page=2&access_token=[REDACTED]"}`, + `{"duration_ms":"","event_id":"","level":"INFO","method":"POST","msg":"response","status":200,"status_text":"OK","uri":"/tasks?page=2&access_token=[REDACTED]"}`, + }, + }, + { + name: "parsed form", + body: "note=formvalue&secret=formsecret", + next: okHandler, parseForm: true, + want: []string{ + `{"event_id":"","headers":{"Authorization":["[REDACTED]"],"Content-Type":["application/x-www-form-urlencoded"],"Cookie":["[REDACTED]"]},"level":"INFO","method":"POST","msg":"request","uri":"/tasks?page=2&access_token=[REDACTED]"}`, + `{"duration_ms":"","event_id":"","level":"INFO","method":"POST","msg":"response","status":200,"status_text":"OK","uri":"/tasks?page=2&access_token=[REDACTED]"}`, + }, + }, + { + name: "bad json", + body: `{"title":`, + want: []string{`{"error":"unexpected EOF","level":"ERROR","msg":"request body rejected"}`}, + }, + { + name: "panic", + next: func(http.ResponseWriter, *http.Request) { panic("boom") }, + want: []string{ + `{"event_id":"","headers":{"Authorization":["[REDACTED]"],"Cookie":["[REDACTED]"]},"level":"INFO","method":"POST","msg":"request","uri":"/tasks?page=2&access_token=[REDACTED]"}`, + `{"event_id":"","level":"ERROR","msg":"panic recovered","panic":"boom"}`, + }, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + buf := captureDefaultLogger(t) + next := tt.next + if next == nil { + next = okHandler + } + handler := ProcessRequest(next) + if tt.parseForm { + handler = parseFormFirst(t, handler) + } + req := httptest.NewRequest(http.MethodPost, "/tasks?page=2&access_token=s3cr3t", strings.NewReader(tt.body)) + req.Header.Set("Authorization", "Bearer s3cr3t") + req.Header.Set("Cookie", "sid=s3cr3t") + if tt.parseForm { + req.Header.Set("Content-Type", "application/x-www-form-urlencoded") + } + + handler.ServeHTTP(httptest.NewRecorder(), req) + + records := decodeRecords(t, buf) + var got []string + for _, record := range records { + got = append(got, goldenRecord(t, record)) + } + if !slices.Equal(got, tt.want) { + t.Fatalf("records =\n%s\nwant\n%s", strings.Join(got, "\n"), strings.Join(tt.want, "\n")) + } + for _, secret := range []string{"s3cr3t", "bodysecret", "formvalue", "formsecret"} { + if strings.Contains(buf.String(), secret) { + t.Fatalf("records contain %s: %s", secret, buf) + } + } + for _, record := range records { + if record["msg"] == "request" && record["uri"] != "/tasks?page=2&access_token=[REDACTED]" { + t.Fatalf("request uri = %v, want the token masked", record["uri"]) + } + } + }) + } +} + +func TestDefaultGetValueHelperFailuresAreRecorded(t *testing.T) { + tests := []struct { + name string + target string + headers map[string]string + read func(r *http.Request) Response + wantMsg string + wantKey string + wantError string + secret string + }{ + { + name: "header", + headers: map[string]string{"X-Count": "many"}, + read: func(r *http.Request) Response { _, response := GetHeaderValueInt("X-Count", r); return response }, + wantMsg: "header value not obtained", + wantKey: "X-Count", + wantError: `strconv.Atoi: parsing "many": invalid syntax`, + }, + { + name: "sensitive header", + headers: map[string]string{"X-Api-Key": "supersecret"}, + read: func(r *http.Request) Response { _, response := GetHeaderValueInt("X-Api-Key", r); return response }, + wantMsg: "header value not obtained", + wantKey: "X-Api-Key", + wantError: "invalid syntax", + secret: "supersecret", + }, + { + name: "sensitive query param", + target: "/?access_token=supersecret", + read: func(r *http.Request) Response { + _, response := GetQueryParamValueInt("access_token", r) + return response + }, + wantMsg: "query param not obtained", + wantKey: "access_token", + wantError: "invalid syntax", + secret: "supersecret", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + buf := captureDefaultLogger(t) + failOnPackageLoggers(t) + target := tt.target + if target == "" { + target = "/" + } + req := httptest.NewRequest(http.MethodGet, target, nil) + for key, value := range tt.headers { + req.Header.Set(key, value) + } + + if response := tt.read(req); response == nil { + t.Fatal("helper succeeded, want a failure") + } + + records := decodeRecords(t, buf) + if len(records) != 1 { + t.Fatalf("records = %d, want 1 (%s)", len(records), buf) + } + record := records[0] + if record["level"] != "ERROR" || record["msg"] != tt.wantMsg || record["key"] != tt.wantKey || record["error"] != tt.wantError { + t.Fatalf("record = %v, want ERROR %q key %q error %q", record, tt.wantMsg, tt.wantKey, tt.wantError) + } + if tt.secret != "" && strings.Contains(buf.String(), tt.secret) { + t.Fatalf("records contain the value: %s", buf) + } + }) + } +} + +// goldenRecord returns record as JSON without its time, with the event ID +// and the duration normalized, so runs can be compared. +func goldenRecord(t *testing.T, record logRecord) string { + t.Helper() + delete(record, "time") + if _, ok := record["event_id"]; ok { + record["event_id"] = "" + } + if _, ok := record["duration_ms"]; ok { + record["duration_ms"] = "" + } + var golden bytes.Buffer + encoder := json.NewEncoder(&golden) + encoder.SetEscapeHTML(false) + if err := encoder.Encode(record); err != nil { + t.Fatalf("encoding record %v: %v", record, err) + } + return strings.TrimSpace(golden.String()) +} + +func TestDefaultSensitiveLogKeysOnlyAdd(t *testing.T) { + buf := captureDefaultLogger(t) + previous := SensitiveLogKeys + SensitiveLogKeys = []string{"pin"} + t.Cleanup(func() { SensitiveLogKeys = previous }) + req := httptest.NewRequest(http.MethodGet, "/tasks", nil) + req.Header.Set("Pin", "1234") + req.Header.Set("Authorization", "Bearer s3cr3t") + + ProcessRequest(okHandler).ServeHTTP(httptest.NewRecorder(), req) + + headers := recordNamed(t, decodeRecords(t, buf), "request")["headers"].(map[string]any) + for _, key := range []string{"Pin", "Authorization"} { + if got := headers[key].([]any)[0]; got != redactedLogValue { + t.Errorf("header %s = %v, want %s", key, got, redactedLogValue) + } + } +} + +func TestDefaultWriterAnswers500WhenResponseCannotBeEncoded(t *testing.T) { + usePackageModes(t, RequestModePlain, ResponseModeEnvelope) + buf := captureDefaultLogger(t) + failOnPackageLoggers(t) + + rec := serve(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + SuccessWithContent(math.NaN()).Write(w, r) + }), http.MethodGet, "", nil) + + if rec.Code != http.StatusInternalServerError { + t.Fatalf("status = %d, want 500", rec.Code) + } + if title, code := envelopeHeader(t, rec.Body.Bytes()); title != InternalServerTitle || code != string(internalServerErrorCode()) { + t.Fatalf("title, code = %q, %q, want the Error500 body", title, code) + } + recordNamed(t, decodeRecords(t, buf), "response cannot be encoded") +} + +func TestDefaultWriterAnswersBare500WhenTheFormatterReturnsNoBody(t *testing.T) { + captureDefaultLogger(t) + RegisterNewAPIResponseFormatter(nanFormatter{}) + t.Cleanup(func() { RegisterNewAPIResponseFormatter(ResponseFormatter{}) }) + + rec := serve(http.HandlerFunc(okHandler), http.MethodGet, "", nil) + + if rec.Code != http.StatusInternalServerError || rec.Body.Len() != 0 { + t.Fatalf("status, body = %d, %q, want a bare 500", rec.Code, rec.Body) + } +} + +func TestNewWithoutLoggerStaysSilentUnderACapturingDefault(t *testing.T) { + buf := captureDefaultLogger(t) + + serve(New().Handler(ProcessRequest(okHandler)), http.MethodPost, `{"title":`, nil) + serve(New().Handler(ProcessRequest(okHandler)), http.MethodPost, `{"title":"task"}`, nil) + + if buf.Len() != 0 { + t.Fatalf("New() without WithLogger logged: %s", buf) + } +} + +// parseFormFirst parses the request form before next runs. +func parseFormFirst(t *testing.T, next http.HandlerFunc) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + if err := r.ParseForm(); err != nil { + t.Fatalf("parsing form: %v", err) + } + next(w, r) + } +} diff --git a/default_log_golden_test.go b/default_log_golden_test.go deleted file mode 100644 index b9d37cd..0000000 --- a/default_log_golden_test.go +++ /dev/null @@ -1,159 +0,0 @@ -package api - -import ( - "bytes" - "fmt" - "net/http" - "net/http/httptest" - "regexp" - "testing" -) - -var ( - eventIDPattern = regexp.MustCompile(`event_id="[^"]*"`) - durationMsPattern = regexp.MustCompile(`duration_ms=\d+`) -) - -// captureDefaultLogLines replaces Print and PrintError for one test and -// returns the lines they would have written, with the event ID and the -// duration normalized so that runs can be compared. -func captureDefaultLogLines(t *testing.T) *[]string { - t.Helper() - previousPrint, previousPrintError := Print, PrintError - lines := []string{} - normalize := func(line string) string { - line = eventIDPattern.ReplaceAllString(line, `event_id=""`) - return durationMsPattern.ReplaceAllString(line, "duration_ms=") - } - Print = func(format string, args ...interface{}) { - lines = append(lines, "Print: "+normalize(fmt.Sprintf(format, args...))) - } - PrintError = func(args ...interface{}) { - lines = append(lines, "PrintError: "+normalize(fmt.Sprint(args...))) - } - t.Cleanup(func() { - Print, PrintError = previousPrint, previousPrintError - }) - return &lines -} - -// TestDefaultInstanceLogLinesMatchV0 pins the lines the default instance -// writes through Print and PrintError. The wanted lines were captured by -// running this test on v0.11.0 (b917197), so the default instance stays -// byte-identical to the latest v0 release. -func TestDefaultInstanceLogLinesMatchV0(t *testing.T) { - tests := []struct { - name string - body string - // next is the handler behind ProcessRequest; nil answers Success200. - next http.HandlerFunc - // parseForm parses the form before ProcessRequest runs. - parseForm bool - // logRequestBody sets LogRequestBody for the test. - logRequestBody bool - want []string - }{ - { - name: "success", - body: `{"title":"task"}`, - want: []string{ - `Print: REQUEST event_id="" method="POST" uri="/tasks?page=2&access_token=[REDACTED]" headers={"Authorization":["[REDACTED]"],"Content-Type":["application/json"],"Cookie":["[REDACTED]"]}`, - `Print: RESPONSE event_id="" status=200 status_text="OK" duration_ms=`, - }, - }, - { - name: "bad json", - body: `{"title":`, - want: []string{ - `PrintError: unexpected EOF`, - }, - }, - { - name: "error panic", - next: func(http.ResponseWriter, *http.Request) { panic(goldenPanicError) }, - want: []string{ - `Print: REQUEST event_id="" method="POST" uri="/tasks?page=2&access_token=[REDACTED]" headers={"Authorization":["[REDACTED]"],"Content-Type":["application/json"],"Cookie":["[REDACTED]"]}`, - `PrintError: boom`, - }, - }, - { - name: "non-error panic", - next: func(http.ResponseWriter, *http.Request) { panic("boom") }, - want: []string{ - `Print: REQUEST event_id="" method="POST" uri="/tasks?page=2&access_token=[REDACTED]" headers={"Authorization":["[REDACTED]"],"Content-Type":["application/json"],"Cookie":["[REDACTED]"]}`, - `PrintError: Not response: boom`, - }, - }, - { - name: "logged body", - body: `{"title":"task","password":"s3cr3t"}`, - logRequestBody: true, - want: []string{ - `Print: REQUEST event_id="" method="POST" uri="/tasks?page=2&access_token=[REDACTED]" headers={"Authorization":["[REDACTED]"],"Content-Type":["application/json"],"Cookie":["[REDACTED]"]} body="{\"password\":\"[REDACTED]\",\"title\":\"task\"}"`, - `Print: RESPONSE event_id="" status=200 status_text="OK" duration_ms=`, - }, - }, - { - name: "parsed form", - parseForm: true, - want: []string{ - `Print: REQUEST event_id="" method="POST" uri="/tasks?page=2&access_token=[REDACTED]" form="access_token=[REDACTED]&page=2" headers={"Authorization":["[REDACTED]"],"Content-Type":["application/json"],"Cookie":["[REDACTED]"]}`, - `Print: RESPONSE event_id="" status=200 status_text="OK" duration_ms=`, - }, - }, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - lines := captureDefaultLogLines(t) - previousLogRequestBody := LogRequestBody - LogRequestBody = tt.logRequestBody - t.Cleanup(func() { LogRequestBody = previousLogRequestBody }) - next := tt.next - if next == nil { - next = func(w http.ResponseWriter, r *http.Request) { - Success200().Write(w, r) - } - } - handler := ProcessRequest(next) - if tt.parseForm { - handler = parseFormFirst(t, handler) - } - req := httptest.NewRequest(http.MethodPost, "/tasks?page=2&access_token=s3cr3t", bytes.NewBufferString(tt.body)) - req.Header.Set("Authorization", "Bearer s3cr3t") - req.Header.Set("Content-Type", "application/json") - req.Header.Set("Cookie", "sid=s3cr3t") - - handler.ServeHTTP(httptest.NewRecorder(), req) - - if fmt.Sprintf("%q", *lines) != fmt.Sprintf("%q", tt.want) { - t.Fatalf("log lines =\n%s\nwant\n%s", joinLines(*lines), joinLines(tt.want)) - } - }) - } -} - -var goldenPanicError = goldenError("boom") - -// goldenError is an error type that exists on v0.11.0 too, so this file -// compiles there unchanged. -type goldenError string - -func (e goldenError) Error() string { return string(e) } - -// parseFormFirst parses the request form before next runs. -func parseFormFirst(t *testing.T, next http.HandlerFunc) http.HandlerFunc { - return func(w http.ResponseWriter, r *http.Request) { - if err := r.ParseForm(); err != nil { - t.Fatalf("parsing form: %v", err) - } - next(w, r) - } -} - -func joinLines(lines []string) string { - var out bytes.Buffer - for _, line := range lines { - out.WriteString(line + "\n") - } - return out.String() -} diff --git a/doc.go b/doc.go index 27136ca..0f8651a 100644 --- a/doc.go +++ b/doc.go @@ -8,8 +8,8 @@ // writers and middlewares then use that instance for the request. // // Without an instance, the package-level functions use a default instance -// that answers like New() with its defaults. It logs through Print and -// PrintError, and the deprecated package variables and RegisterNew* -// functions still configure its modes, sensitive keys and components; see +// that behaves like New() with its defaults. It logs through slog.Default, +// and the deprecated package variables and RegisterNew* functions still +// configure its modes, sensitive keys and components; see // docs/migration-v1.md for the move to New. package api diff --git a/docs/legacy.md b/docs/legacy.md index e7e1136..65635c6 100644 --- a/docs/legacy.md +++ b/docs/legacy.md @@ -131,7 +131,7 @@ Two exported implementations of `core.APIRequestReceiver` exist. Both follow the ### `api.Response`-returning helpers -These helpers predate `api.WriteError` and the `Query*` helpers. They return a ready-to-write `api.Response` (an `api.Error`) instead of an `error`, and log the underlying error: with `api.PrintError` on the default instance, through the `api.WithLogger` logger (or not at all) on an `api.New` instance. +These helpers predate `api.WriteError` and the `Query*` helpers. They return a ready-to-write `api.Response` (an `api.Error`) instead of an `error`, and log the underlying error: through `slog.Default` on the default instance, through the `api.WithLogger` logger (or not at all) on an `api.New` instance. | Helper | Prefer in new code | | --- | --- | diff --git a/docs/migration-v1.md b/docs/migration-v1.md index 1394d7e..0aaead5 100644 --- a/docs/migration-v1.md +++ b/docs/migration-v1.md @@ -6,7 +6,7 @@ This guide takes a v0 program (v0.11.x) to `github.com/jgolang/api` v1. The desi - The module path does not change. When v1.0.0 is tagged, upgrade with `go get github.com/jgolang/api@v1.0.0`; no import changes. - v1 removes nothing. Every v0 name still compiles. Names replaced by an instance option are deprecated, and each one points at its option or says it is ignored. -- **Breaking: the default instance behaves like `api.New()`** (owner decision, 2026-11-21). A program that does not change its code still gets v1's defaults: codes as declared, no request token echo and request bodies bounded at 10 MiB ([step 1](#step-1-upgrade-what-changes-without-code-changes)). A program that needs v0.11.0 behavior stays on v0.11.x. +- **Breaking: the default instance behaves like `api.New()`** (owner decision, 2026-11-21). A program that does not change its code still gets v1's defaults: codes as declared, no request token echo, request bodies bounded at 10 MiB, and `slog` records through `slog.Default` instead of `Print`/`PrintError` ([step 1](#step-1-upgrade-what-changes-without-code-changes)). A program that needs v0.11.0 behavior stays on v0.11.x. - `stdadapter` routes through Go 1.22 `ServeMux` patterns ([step 2](#step-2-fix-routing-stdadapter)). - Configuration moves from package variables to an instance: `a := api.New(opts...)` and `a.Handler(router)` ([step 3](#step-3-move-to-apinew)). Handler code does not change, and it is the only way back to v0's lowercase codes (`api.WithLowercaseCodes()`). - Programs that use `api.BasicToken` no longer get the password in the `Basic-Secret` request header ([details](#breaking-no-basic-secret-header)). @@ -19,7 +19,7 @@ Three steps. Step 1 is the upgrade itself; read it before you ship it. ## Step 1: upgrade: what changes without code changes -Requests that no `a.Handler` wraps use the default instance. Since v1.0.0 it answers like `api.New()` with its defaults. `TestDefaultInstanceAnswersLikeNew` in `default_instance_test.go` checks that status, headers and body are the same as under `api.New().Handler`, apart from event IDs. +Requests that no `a.Handler` wraps use the default instance. Since v1.0.0 it answers and logs like `api.New()` with its defaults. `TestDefaultInstanceAnswersLikeNew` in `default_instance_test.go` checks that status, headers and body are the same as under `api.New().Handler`, apart from event IDs. **Wire changes** (clients, alerts and dashboards may need to change): @@ -31,12 +31,15 @@ Requests that no `a.Handler` wraps use the default instance. Since v1.0.0 it ans - A non-empty `Content-Type` set in a response's `Headers` is now sent. v0 overwrote it with `application/json`. It is a fix, not a breaking change: v0 discarded a `Content-Type` the service set. An empty value counts as unset, and a `Content-Type` the handler set on `w.Header()` is still overwritten, as in v0. - `RequestBasic.GetSecurityToken`, `GetUserID` and `GetEventID` (and so `GetRequestBasicInfo` and `GetRequestFullInfo`) return their own error: title `Request info error!` and the message `The session id was not obtained` (`user id`, `event id`). v0 meant to send it but returned the generic `Error getting header value!` / `The key header has not been obtained` instead (#63). -**Logging** is unchanged from v0.11.0: +**Logging changes:** -- Logging goes through `Print` and `PrintError` and writes the same lines as v0.11.0. A response that cannot be encoded is answered with 500, as in v0.11.0; `Fatal` is never called. That 500 now drops the failed body's `Content-Type`, `Content-Encoding`, `Content-Length` and similar headers, and answers with no body instead of panicking when a registered formatter returns nil. -- `SensitiveLogKeys` keeps its v0.11.0 list (with `cookie` and `session`) and masking (headers, JSON body fields, query and form values, the user information of the `uri`). +- `ProcessRequest` writes `slog` records through `slog.Default()`, read at call time: `request` and `response` info records, `request body rejected`, `panic recovered` and the `Get*Value*` helper failures as error records, the same records an instance writes with `WithLogger` (see the README "Logging" section). `slog.Default()` writes through the standard `log` package unless you call `slog.SetDefault`. +- `Print` and `PrintError` are never called by the package any more; only the deprecated `LogRequest`, `LogResponse` and `LogResponseWithDuration` call `Print`. A service that replaced them to route logs must call `slog.SetDefault` with its handler, or move to `api.WithLogger` ([step 3](#step-3-move-to-apinew)). `Fatal` is never called, as since v0.11.0. +- Bodies and the parsed form are never logged. `LogRequestBody`, `LogResponseBody`, `PrintFullEvent` and `MaxLoggedBodyBytes` now affect only the deprecated `Log*` functions. +- Header values and the query values in `uri` whose key is sensitive are masked, as is the `uri`'s user information. The keys are the built-in list plus `SensitiveLogKeys`: the variable can add keys but no longer remove a built-in one. +- A response that cannot be encoded is answered with 500 and the registered formatter's `Error500()` body (bare 500 if it returns nil), and logged as `response cannot be encoded`. -**What still configures the default instance:** `SetRequestMode`, `SetResponseMode` (`CurrentRequestMode`, `CurrentResponseMode`), `TraceVisibility`, `TraceIDLength`, `BlankSuccess`, `SensitiveLogKeys`, the body-logging variables and the components set with `RegisterNewAPIRequestReceiver`, `RegisterNewAPIResponseFormatter` and `RegisterNewAPIResponseWriter`. +**What still configures the default instance:** `SetRequestMode`, `SetResponseMode` (`CurrentRequestMode`, `CurrentResponseMode`), `TraceVisibility`, `TraceIDLength`, `BlankSuccess`, `SensitiveLogKeys` (adds only) and the components set with `RegisterNewAPIRequestReceiver`, `RegisterNewAPIResponseFormatter` and `RegisterNewAPIResponseWriter`. Deprecated names are reported by staticcheck (`SA1019`) and by gopls in your editor. `go vet` does not report them. Fix the routing first (step 2); the deprecations can wait until step 3. @@ -120,11 +123,11 @@ The handler answers byte for byte as on the default instance. `WithLowercaseCode `Example_migrationBeforeAndAfter` in `example_migration_test.go` proves it for the handler, served without `ProcessRequest`. Under `ProcessRequest` the bodies also match apart from the generated event IDs; `TestQuickStartAnswersLikeTheDefaultInstance` in `instance_test.go` covers that. -**Wrap the outermost chain.** Middlewares outside `a.Handler` use the default instance. So does `api.Write(data, w)`, which takes no request. Put `a.Handler` around everything, or a rejection from an outer `ProcessRequest` uses the package modes, logs through `Print`/`PrintError` instead of the instance logger and is bounded at 10 MiB instead of the instance's limit. With nested instances, the innermost one wins. +**Wrap the outermost chain.** Middlewares outside `a.Handler` use the default instance. So does `api.Write(data, w)`, which takes no request. Put `a.Handler` around everything, or a rejection from an outer `ProcessRequest` uses the package modes, logs through `slog.Default` instead of the instance logger and is bounded at 10 MiB instead of the instance's limit. With nested instances, the innermost one wins. ### Deprecated names and their options -The names replaced by an instance option keep working, but only for the default instance. The `GetQueryParamValue*` helpers and `ResponseCodes.InternalServerEerror` keep working everywhere, instances included. +The names replaced by an instance option keep working, but only for the default instance; the ones marked "ignored" have no effect on the package any more. The `GetQueryParamValue*` helpers and `ResponseCodes.InternalServerEerror` keep working everywhere, instances included. | Deprecated (v0) | Use instead | |---|---| @@ -135,12 +138,13 @@ The names replaced by an instance option keep working, but only for the default | `RegisterNewAPIRequestReceiver` | `api.New(api.WithRequestReceiver(...))` | | `RegisterNewAPIResponseFormatter` | `api.New(api.WithResponseFormatter(...))` | | `RegisterNewAPIResponseWriter` | `api.New(api.WithResponseWriter(...))` | -| `Print` | `api.New(api.WithLogger(...))` | -| `PrintError` | `api.New(api.WithLogger(...))` | -| `Fatal` | `api.New(api.WithLogger(...))` | +| `Print` | `api.New(api.WithLogger(...))` or `slog.SetDefault` (called only by the deprecated `Log*`) | +| `PrintError` | `api.New(api.WithLogger(...))` or `slog.SetDefault` (ignored) | +| `Fatal` | `api.New(api.WithLogger(...))` or `slog.SetDefault` (ignored) | | `LogRequest` | `api.New(api.WithLogger(...))` | | `LogResponse` | `api.New(api.WithLogger(...))` | | `LogResponseWithDuration` | `api.New(api.WithLogger(...))` | +| `LogRequestBody`, `LogResponseBody`, `PrintFullEvent`, `MaxLoggedBodyBytes` | none: bodies are never logged (they affect only the deprecated `Log*`) | | `SensitiveLogKeys` | `api.New(api.WithSensitiveLogKeys(...))` | | `GetQueryParamValueString` | `api.QueryString` (deprecated since v0.9.0) | | `GetQueryParamValueInt` | `api.QueryInt` (deprecated since v0.9.0) | @@ -156,14 +160,14 @@ a := api.New( api.WithRequestReceiver(api.RequestReceiver{}), // RegisterNewAPIRequestReceiver api.WithResponseFormatter(api.ResponseFormatter{}), // RegisterNewAPIResponseFormatter api.WithResponseWriter(api.ResponseWriter{}), // RegisterNewAPIResponseWriter - api.WithLogger(logger), // Print, PrintError, Fatal, Log* + api.WithLogger(logger), // slog.Default; Print, PrintError, Fatal, Log* api.WithSensitiveLogKeys("pin"), // SensitiveLogKeys ) ``` `Example_migrationOptions` is the compiled version. Pass only the options you need: `api.New()` already uses the built-in receiver, formatter and writer. -**Custom components.** The mode options, and `WithLowercaseCodes` for the formatter, apply to the built-in `RequestReceiver`, `RequestReceiverV2` and `ResponseFormatter`, also when you pass them with an option. A custom receiver or formatter decides on its own how it parses, what body it writes and its code text. A type that embeds a built-in one is custom: its promoted methods read the deprecated package mode variables and send codes as declared. A type that embeds `ResponseWriter` behaves as the default instance's writer: it logs through `PrintError` and builds its 500 body with the registered formatter. A nil value keeps the built-in. +**Custom components.** The mode options, and `WithLowercaseCodes` for the formatter, apply to the built-in `RequestReceiver`, `RequestReceiverV2` and `ResponseFormatter`, also when you pass them with an option. A custom receiver or formatter decides on its own how it parses, what body it writes and its code text. A type that embeds a built-in one is custom: its promoted methods read the deprecated package mode variables and send codes as declared. A type that embeds `ResponseWriter` behaves as the default instance's writer: it logs through `slog.Default` and builds its 500 body with the registered formatter. A nil value keeps the built-in. ### What stays package-level @@ -178,7 +182,7 @@ These are not deprecated and are shared by every instance: - `RegisterNewAPISecurityGuarantor` and `RegisterParamValidator`: every instance forwards to them; - `Write(data, w)`. -`TraceVisibility`, `TraceIDLength`, `BlankSuccess`, `PrintFullEvent`, `LogRequestBody`, `LogResponseBody` and `MaxLoggedBodyBytes` are not deprecated either, but they affect only the default instance. Instances use their v0 defaults and never log bodies. +`TraceVisibility`, `TraceIDLength` and `BlankSuccess` are not deprecated either (no instance option replaces them), but they affect only the default instance. ## What an instance adds @@ -199,13 +203,13 @@ a := api.New( `Example_migrationKindStatusAndHook` is the compiled version. -**Logging.** An instance logs only through its `WithLogger` logger, as `slog` records (`request`, `response`, and error records). Without a logger it logs nothing. Compared with the default instance: +**Logging.** An instance logs only through its `WithLogger` logger, with the same `slog` records as the default instance (`request`, `response`, and error records). Without a logger it logs nothing; the default instance logs through `slog.Default` instead. Both: -- the sensitive keys are the default `SensitiveLogKeys` list, copied when the instance is built, plus `WithSensitiveLogKeys`, which only adds; changing `SensitiveLogKeys` does not reach an instance; -- header values, query values in `uri` (`/login?access_token=[REDACTED]&page=2`) and the user information of the `uri` (`http://[REDACTED]@host/...`) are masked with the same rules as the default instance; path segments are not; -- bodies and the parsed form are never logged; -- a failed `Get*Value*` helper logs the name as `key`; for a sensitive name the `error` gives only the kind of failure, never the value; -- the built-in writer never calls `Fatal` and never exits: a body that cannot be encoded is logged and answered with 500 and the `Error500()` body, with the formatter's `Content-Type`. The failed response's headers that describe its body (`Content-Type`, `Content-Encoding`, `Content-Length`, `ETag`, …) are dropped from that 500; the others are kept. +- mask the built-in sensitive keys plus the added ones: `WithSensitiveLogKeys` on an instance, `SensitiveLogKeys` on the default instance; changing `SensitiveLogKeys` does not reach an instance; +- mask header values, query values in `uri` (`/login?access_token=[REDACTED]&page=2`) and the user information of the `uri` (`http://[REDACTED]@host/...`); path segments are not; +- never log bodies or the parsed form; +- log a failed `Get*Value*` helper with the name as `key`; for a sensitive name the `error` gives only the kind of failure, never the value; +- never call `Fatal` or exit from the built-in writer: a body that cannot be encoded is logged and answered with 500 and the `Error500()` body, with the formatter's `Content-Type`. The failed response's headers that describe its body (`Content-Type`, `Content-Encoding`, `Content-Length`, `ETag`, …) are dropped from that 500; the others are kept. See the README "Logging" section for every record. @@ -236,6 +240,7 @@ a.Handler(http.HandlerFunc(createTask)).ServeHTTP(rec, req) - [ ] Upgrade and build. Nothing is removed, so the program compiles. - [ ] Check clients, alerts and dashboards that match lowercase codes (`e001`), read the request token back from responses or from the `SecurityToken` response header, or send bodies over 10 MiB ([step 1](#step-1-upgrade-what-changes-without-code-changes)). - [ ] If clients send bodies over 10 MiB, raise the limit with `api.New(api.WithMaxBodyBytes(n)).Handler`; `http.MaxBytesHandler` can only lower it. +- [ ] If you replaced `Print` or `PrintError` to route logs, call `slog.SetDefault` (or move to `api.WithLogger`). - [ ] Start the service once (or build its router in a test): fix every registration panic (conflicts, methods, wildcard names). - [ ] Check trailing-slash clients, HEAD skip paths, 405 handling and `GODEBUG=httpmuxgo121`. - [ ] Validate route variables that reach file paths, headers or logs. diff --git a/example_migration_test.go b/example_migration_test.go index 4a195f8..9d9f5bb 100644 --- a/example_migration_test.go +++ b/example_migration_test.go @@ -98,7 +98,7 @@ func Example_migrationOptions() { api.WithRequestReceiver(api.RequestReceiver{}), // RegisterNewAPIRequestReceiver api.WithResponseFormatter(api.ResponseFormatter{}), // RegisterNewAPIResponseFormatter api.WithResponseWriter(api.ResponseWriter{}), // RegisterNewAPIResponseWriter - api.WithLogger(logger), // Print, PrintError, Fatal, Log* + api.WithLogger(logger), // slog.Default; Print, PrintError, Fatal, Log* api.WithSensitiveLogKeys("pin"), // SensitiveLogKeys ) diff --git a/functions.go b/functions.go index ffbc967..a272184 100644 --- a/functions.go +++ b/functions.go @@ -15,24 +15,27 @@ import ( "github.com/jgolang/api/core" ) -// PrintError wrapper function. It affects only the default instance; an -// instance from New logs errors through its WithLogger logger. +// PrintError wrapper function. Since v1.0.0 the package no longer calls it: +// the default instance logs errors through slog.Default and an instance from +// New through its WithLogger logger. // -// Deprecated: use api.New(api.WithLogger(...)) instead. +// Deprecated: it is ignored; use api.New(api.WithLogger(...)) or +// slog.SetDefault instead. var PrintError func(...interface{}) = log.Print -// Print wrapper function. It affects only the default instance; an instance -// from New logs requests and responses through its WithLogger logger. +// Print wrapper function. Since v1.0.0 only the deprecated LogRequest, +// LogResponse and LogResponseWithDuration call it: the default instance logs +// requests and responses through slog.Default and an instance from New +// through its WithLogger logger. // -// Deprecated: use api.New(api.WithLogger(...)) instead. +// Deprecated: use api.New(api.WithLogger(...)) or slog.SetDefault instead. var Print func(string, ...interface{}) = log.Printf // Fatal wrapper function. The package no longer calls it: a response that -// cannot be encoded is reported through PrintError and answered with 500 on -// the default instance, and through the WithLogger logger on an instance -// from New. +// cannot be encoded is logged and answered with 500. // -// Deprecated: use api.New(api.WithLogger(...)) instead. +// Deprecated: it is ignored; use api.New(api.WithLogger(...)) or +// slog.SetDefault instead. var Fatal func(...interface{}) = log.Fatal // GetHeaderValueString gets header value as string. @@ -374,24 +377,37 @@ const redactedLogValue = "[REDACTED]" // PrintFullEvent set true value for allow print full event request. It also // logs a non-JSON request body as is instead of its size. +// +// Deprecated: it affects only the deprecated LogRequest, LogResponse and +// LogResponseWithDuration; ProcessRequest never logs bodies. var PrintFullEvent bool = false // LogRequestBody enables request body logging. +// +// Deprecated: it affects only the deprecated LogRequest; ProcessRequest +// never logs bodies. var LogRequestBody bool = false // LogResponseBody enables response body logging. +// +// Deprecated: it affects only the deprecated LogResponse and +// LogResponseWithDuration; ProcessRequest never logs bodies. var LogResponseBody bool = false // MaxLoggedBodyBytes limits logged request and response bodies when PrintFullEvent is false. +// +// Deprecated: it affects only the deprecated LogRequest, LogResponse and +// LogResponseWithDuration; ProcessRequest never logs bodies. var MaxLoggedBodyBytes int = 2000 // SensitiveLogKeys defines fields, headers and query parameters that must be // redacted in logs: by default authorization, token, password, secret, // credential, apikey, api-key, key, cookie and session. A name is sensitive // when it contains one of the keys, ignoring case. -// It affects only the default instance, which reads it at call time; an -// instance from New masks the default keys plus the keys added with -// WithSensitiveLogKeys. +// The default instance reads it at call time and masks the built-in keys +// plus these, so it can add keys but no longer remove a built-in one; an +// instance from New masks the built-in keys plus the keys added with +// WithSensitiveLogKeys. The deprecated LogRequest masks only these keys. // // Deprecated: use api.New(api.WithSensitiveLogKeys(...)) instead. var SensitiveLogKeys = defaultSensitiveLogKeys() @@ -417,8 +433,8 @@ func defaultSensitiveLogKeys() []string { // JSON body fields, query parameters in uri and form fields are masked (see // SensitiveLogKeys), as is the user information of an absolute-form uri. A // request body that is not JSON is logged as its size unless PrintFullEvent -// is true. It writes only the default instance's lines; an instance from New -// logs through its WithLogger logger. +// is true. The package no longer calls it: ProcessRequest logs through +// slog.Default, or through the instance's WithLogger logger. // // Deprecated: use api.New(api.WithLogger(...)) instead. func LogRequest(method, uri, eventID, form string, headers http.Header, rawBody []byte) { @@ -439,8 +455,9 @@ func LogRequest(method, uri, eventID, form string, headers http.Header, rawBody Print(format, args...) } -// LogResponse prints API response in log. It writes only the default -// instance's lines; an instance from New logs through its WithLogger logger. +// LogResponse prints API response in log. The package no longer calls it: +// ProcessRequest logs through slog.Default, or through the instance's +// WithLogger logger. // // Deprecated: use api.New(api.WithLogger(...)) instead. func LogResponse(eventID string, res *httptest.ResponseRecorder) { @@ -448,8 +465,8 @@ func LogResponse(eventID string, res *httptest.ResponseRecorder) { } // LogResponseWithDuration prints API response in log including request -// duration. It writes only the default instance's lines; an instance from New -// logs through its WithLogger logger. +// duration. The package no longer calls it: ProcessRequest logs through +// slog.Default, or through the instance's WithLogger logger. // // Deprecated: use api.New(api.WithLogger(...)) instead. func LogResponseWithDuration(eventID string, res *httptest.ResponseRecorder, duration time.Duration) { diff --git a/functions_logging_test.go b/functions_logging_test.go index df22b9f..830d40e 100644 --- a/functions_logging_test.go +++ b/functions_logging_test.go @@ -312,20 +312,14 @@ func TestLogRequestRedactsSensitiveFormValues(t *testing.T) { } } -// The built-in receivers reject a non-JSON body before ProcessRequest logs, -// so this end-to-end case covers the cookie, the query and a JSON body. -func TestProcessRequestLogRedactsCookieQueryAndJSONBody(t *testing.T) { +// TestProcessRequestLogRedactsCookieQueryAndBody checks the default +// ProcessRequest records: the cookie and query token are masked and the body +// is never logged, even with LogRequestBody set. +func TestProcessRequestLogRedactsCookieQueryAndBody(t *testing.T) { + buf := captureDefaultLogger(t) previousLogRequestBody := LogRequestBody - previousPrint := Print LogRequestBody = true - var lines []string - Print = func(format string, args ...interface{}) { - lines = append(lines, fmt.Sprintf(format, args...)) - } - defer func() { - LogRequestBody = previousLogRequestBody - Print = previousPrint - }() + t.Cleanup(func() { LogRequestBody = previousLogRequestBody }) body := `{"password":"secret-password","title":"task"}` req := httptest.NewRequest(http.MethodPost, "/login?token=secret-token&page=1", strings.NewReader(body)) @@ -336,19 +330,16 @@ func TestProcessRequestLogRedactsCookieQueryAndJSONBody(t *testing.T) { handler.ServeHTTP(httptest.NewRecorder(), req) - output := strings.Join(lines, "\n") - for _, value := range []string{"secret-password", "secret-token", "secret-cookie"} { - if strings.Contains(output, value) { - t.Fatalf("expected %q to be absent from the log, got %q", value, output) + for _, value := range []string{"secret-password", "secret-token", "secret-cookie", "title"} { + if strings.Contains(buf.String(), value) { + t.Fatalf("expected %q to be absent from the log, got %s", value, buf) } } - for _, want := range []string{ - `uri="/login?token=[REDACTED]&page=1"`, - `"Cookie":["[REDACTED]"]`, - `title`, - } { - if !strings.Contains(output, want) { - t.Fatalf("expected %s in the log, got %q", want, output) - } + request := recordNamed(t, decodeRecords(t, buf), "request") + if request["uri"] != "/login?token=[REDACTED]&page=1" { + t.Fatalf("uri = %v, want the token masked", request["uri"]) + } + if cookie := request["headers"].(map[string]any)["Cookie"].([]any)[0]; cookie != redactedLogValue { + t.Fatalf("Cookie = %v, want %s", cookie, redactedLogValue) } } diff --git a/instance.go b/instance.go index 3f0efe3..db32477 100644 --- a/instance.go +++ b/instance.go @@ -22,18 +22,21 @@ import ( // // Requests that carry no instance are served by the default instance, which // behaves like New() with its defaults: codes as declared, no request token -// echo and request bodies bounded at 10 MiB where the library reads them. -// It takes its modes, formatter settings and components from the deprecated -// package-level setters, and logs through Print and PrintError, masking -// SensitiveLogKeys. A zero or nil API is the default instance. +// echo, request bodies bounded at 10 MiB where the library reads them, and +// slog records instead of Print and PrintError. It differs from New() only +// in where its configuration comes from: it logs through slog.Default (read +// at call time), masks the default sensitive keys plus SensitiveLogKeys, and +// takes its modes, formatter settings and components from the deprecated +// package-level setters. A zero or nil API is the default instance. type API struct { core *core.API kindStatus map[codes.Kind]int errorHook func(r *http.Request, err error, status int) - // fromNew is true for an API from New; false is the default instance, - // which logs through the v0 package variables. - fromNew bool - logger *slog.Logger + // logger is nil only on the default instance, which logs through + // slog.Default; New always sets one. + logger *slog.Logger + // sensitiveLogKeys is nil only on the default instance, which masks the + // default keys plus SensitiveLogKeys. sensitiveLogKeys []string maxBodyBytes int64 } @@ -80,6 +83,9 @@ func New(opts ...Option) *API { opt(&o) } } + if o.logger == nil { + o.logger = slog.New(slog.DiscardHandler) + } formatter := o.responseFormatter() return &API{ core: core.New( @@ -92,7 +98,6 @@ func New(opts ...Option) *API { ), kindStatus: o.kindStatus, // built by WithKindStatus inside New; nothing else holds it errorHook: o.errorHook, - fromNew: true, logger: o.logger, sensitiveLogKeys: instanceSensitiveLogKeys(o.sensitiveLogKeys), maxBodyBytes: o.maxBodyBytes, @@ -164,7 +169,7 @@ func (o options) bindFormatter(formatter ResponseFormatter) ResponseFormatter { func (o options) responseWriter(formatter core.APIResponseFormatter) core.APIResponseWriter { switch o.writer.(type) { case nil, ResponseWriter, *ResponseWriter: - return ResponseWriter{fromNew: true, logger: o.logger, formatter: formatter} + return ResponseWriter{logger: o.logger, formatter: formatter} default: return o.writer } @@ -347,7 +352,7 @@ func WithResponseFormatter(formatter core.APIResponseFormatter) Option { // with the instance formatter's body. A custom writer alone decides how it // writes and is used as given, including a typed nil pointer. A type that // embeds ResponseWriter is custom: its promoted Write keeps the default -// instance's behavior (PrintError and the registered formatter). +// instance's behavior (slog.Default and the registered formatter). func WithResponseWriter(writer core.APIResponseWriter) Option { return func(o *options) { o.writer = writer @@ -406,7 +411,7 @@ type instanceKey struct{} // defaultInstance serves requests that carry no instance. It wraps the // package-level core, so RegisterNew* and the package mode variables -// configure it. +// configure it; its nil logger and sensitive keys are resolved at call time. var defaultInstance = &API{core: api, maxBodyBytes: defaultMaxBodyBytes} // instanceFrom returns the instance stored in r's context by Handler, or the diff --git a/instance_bench_test.go b/instance_bench_test.go index 5e3e2b0..4b47a05 100644 --- a/instance_bench_test.go +++ b/instance_bench_test.go @@ -2,6 +2,7 @@ package api import ( "context" + "log" "log/slog" "net/http" "net/http/httptest" @@ -68,12 +69,16 @@ func BenchmarkWriteError(b *testing.B) { } // BenchmarkProcessRequest measures ProcessRequest's logging on the default -// instance (with Print as a no-op), on an instance without a logger and on -// one whose logger discards every record. +// instance (with slog.Default discarding every record), on an instance +// without a logger and on one whose logger discards every record. func BenchmarkProcessRequest(b *testing.B) { - previousPrint := Print - Print = func(string, ...interface{}) {} - b.Cleanup(func() { Print = previousPrint }) + previous, previousOutput, previousFlags := slog.Default(), log.Writer(), log.Flags() + slog.SetDefault(slog.New(slog.DiscardHandler)) + b.Cleanup(func() { + slog.SetDefault(previous) + log.SetOutput(previousOutput) + log.SetFlags(previousFlags) + }) handler := ProcessRequest(func(w http.ResponseWriter, r *http.Request) { Success200().Write(w, r) }) diff --git a/instance_log.go b/instance_log.go index 0586e9c..363ce5a 100644 --- a/instance_log.go +++ b/instance_log.go @@ -5,7 +5,6 @@ import ( "context" "encoding/json" "errors" - "fmt" "log/slog" "net/http" "net/http/httptest" @@ -22,44 +21,53 @@ func instanceSensitiveLogKeys(added []string) []string { return append(defaultSensitiveLogKeys(), added...) } -// logs reports whether a writes records at level. The default instance and -// an instance without WithLogger never do. +// log returns the logger a writes through: its own, or slog.Default at call +// time on the default instance. +func (a *API) log() *slog.Logger { + if a.logger == nil { + return slog.Default() + } + return a.logger +} + +// sensitiveKeys returns the keys a masks: its own, or on the default +// instance the default keys plus SensitiveLogKeys at call time, so the +// variable can add keys but never remove a default one. +func (a *API) sensitiveKeys() []string { + if a.sensitiveLogKeys == nil { + return append(defaultSensitiveLogKeys(), SensitiveLogKeys...) + } + return a.sensitiveLogKeys +} + +// logs reports whether a writes records at level. An instance without +// WithLogger never does. func (a *API) logs(ctx context.Context, level slog.Level) bool { - return a.logger != nil && a.logger.Enabled(ctx, level) + return a.log().Enabled(ctx, level) } -// logError reports err, met while serving r. The default instance passes it -// to PrintError as v0 does; an instance from New writes an error record with -// message msg through its logger, if it has one. +// logError writes an error record with message msg for err, met while +// serving r. func (a *API) logError(r *http.Request, msg string, err error) { - if !a.fromNew { - PrintError(err) - return - } if !a.logs(r.Context(), slog.LevelError) { return } - a.logger.LogAttrs(r.Context(), slog.LevelError, msg, slog.Any("error", err)) + a.log().LogAttrs(r.Context(), slog.LevelError, msg, slog.Any("error", err)) } // logNamedError reports err from reading the value of the header, query -// parameter or route variable called name. The default instance passes it to -// PrintError as v0 does. An instance from New adds the name as "key"; when +// parameter or route variable called name. It adds the name as "key"; when // the name is sensitive it logs only the kind of error, since errors such as // strconv's quote the value. func (a *API) logNamedError(r *http.Request, msg, name string, err error) { - if !a.fromNew { - PrintError(err) - return - } if !a.logs(r.Context(), slog.LevelError) { return } errAttr := slog.Any("error", err) - if isSensitiveKey(name, a.sensitiveLogKeys) { + if isSensitiveKey(name, a.sensitiveKeys()) { errAttr = slog.String("error", sensitiveValueError(err)) } - a.logger.LogAttrs(r.Context(), slog.LevelError, msg, slog.String("key", name), errAttr) + a.log().LogAttrs(r.Context(), slog.LevelError, msg, slog.String("key", name), errAttr) } // sensitiveValueError describes err without the value it was reading: the @@ -72,62 +80,44 @@ func sensitiveValueError(err error) string { return "invalid value" } -// logRequest logs the request ProcessRequest received. The default instance -// writes the v0 line through LogRequest, body included when LogRequestBody -// is set; an instance from New never logs the body or the parsed form (it -// may come from the body) and masks the query values whose key is sensitive. -func (a *API) logRequest(r *http.Request, eventID string, rawBody []byte) { - if !a.fromNew { - LogRequest(r.Method, r.RequestURI, eventID, r.Form.Encode(), r.Header, rawBody) - return - } +// logRequest logs the request ProcessRequest received. It never logs the +// body or the parsed form (it may come from the body) and masks the query +// values whose key is sensitive. +func (a *API) logRequest(r *http.Request, eventID string) { if !a.logs(r.Context(), slog.LevelInfo) { return } + sensitiveKeys := a.sensitiveKeys() attrs := []slog.Attr{ slog.String("event_id", eventID), slog.String("method", r.Method), - slog.String("uri", redactURI(r.RequestURI, a.sensitiveLogKeys)), + slog.String("uri", redactURI(r.RequestURI, sensitiveKeys)), } if len(r.Header) != 0 { - attrs = append(attrs, slog.Any("headers", redactHeaders(r.Header, a.sensitiveLogKeys))) + attrs = append(attrs, slog.Any("headers", redactHeaders(r.Header, sensitiveKeys))) } - a.logger.LogAttrs(r.Context(), slog.LevelInfo, "request", attrs...) + a.log().LogAttrs(r.Context(), slog.LevelInfo, "request", attrs...) } // logResponse logs the response ProcessRequest wrote, as logRequest does. func (a *API) logResponse(r *http.Request, eventID string, rec *httptest.ResponseRecorder, duration time.Duration) { - if !a.fromNew { - LogResponseWithDuration(eventID, rec, duration) - return - } if !a.logs(r.Context(), slog.LevelInfo) { return } - a.logger.LogAttrs(r.Context(), slog.LevelInfo, "response", + a.log().LogAttrs(r.Context(), slog.LevelInfo, "response", slog.String("event_id", eventID), slog.String("method", r.Method), - slog.String("uri", redactURI(r.RequestURI, a.sensitiveLogKeys)), + slog.String("uri", redactURI(r.RequestURI, a.sensitiveKeys())), slog.Int("status", rec.Code), slog.String("status_text", http.StatusText(rec.Code)), slog.Int64("duration_ms", duration.Milliseconds()), ) } -// logPanic logs a panic ProcessRequest recovered. The default instance keeps -// the PrintError calls of v0.11.0, which log the panic value; an instance -// from New logs the panic value with the event ID. A panic with -// http.ErrAbortHandler is a deliberate abort, so it is logged at debug level -// as "handler aborted". +// logPanic logs a panic ProcessRequest recovered, with the panic value and +// the event ID. A panic with http.ErrAbortHandler is a deliberate abort, so +// it is logged at debug level as "handler aborted". func (a *API) logPanic(r *http.Request, eventID string, recovered any) { - if !a.fromNew { - if err, ok := recovered.(error); ok { - PrintError(err) - } else { - PrintError("Not response: ", fmt.Sprintf("%v", recovered)) - } - return - } level, msg := slog.LevelError, "panic recovered" if err, ok := recovered.(error); ok && errors.Is(err, http.ErrAbortHandler) { level, msg = slog.LevelDebug, "handler aborted" @@ -135,17 +125,24 @@ func (a *API) logPanic(r *http.Request, eventID string, recovered any) { if !a.logs(r.Context(), level) { return } - a.logger.LogAttrs(r.Context(), level, msg, + a.log().LogAttrs(r.Context(), level, msg, slog.String("event_id", eventID), slog.Any("panic", recovered), ) } -// writeForInstance is the Write of an instance's built-in writer. It encodes -// the body before writing anything, so a body that cannot be encoded (e.g. a -// NaN float) is logged and answered with 500 and the instance formatter's -// internal server error body instead of exiting the process. -func (writer ResponseWriter) writeForInstance(response *core.ResponseFormatted, w http.ResponseWriter) { +// Write the API response in screen. It encodes the body before writing +// anything, so a body that cannot be encoded (e.g. a NaN float) is logged as +// "response cannot be encoded" and answered with 500 and the formatter's +// internal server error body (see writeEncodeFailure) instead of exiting the +// process. If the handler already wrote a status, that status stays and the +// error body is written under it. +// +// http.ErrBodyNotAllowed from writing the body is not reported: Warning and +// Informative default to status 100, which a server sends as informational +// before delivering the body with 200, while the recorder that ProcessRequest +// writes into returns this error. +func (writer ResponseWriter) Write(response *core.ResponseFormatted, w http.ResponseWriter) { var body bytes.Buffer if err := json.NewEncoder(&body).Encode(response.Body); err != nil { writer.logError("response cannot be encoded", err) @@ -156,7 +153,7 @@ func (writer ResponseWriter) writeForInstance(response *core.ResponseFormatted, } // writeEncodeFailure answers 500 with the internal server error body built by -// the instance's formatter, keeping the response headers except the ones +// the writer's formatter, keeping the response headers except the ones // that described the failed body (withoutBodyHeaders); the error body's own // Content-Type applies. The body carries no event ID or token, since the // request is not available here. If the formatter returns no body, or it @@ -165,7 +162,7 @@ func (writer ResponseWriter) writeForInstance(response *core.ResponseFormatted, func (writer ResponseWriter) writeEncodeFailure(headers map[string]string, w http.ResponseWriter) { headers = withoutBodyHeaders(headers) failure := Error500() - formatted := writer.formatter.Format(core.ResponseData{ + formatted := writer.responseFormatter().Format(core.ResponseData{ Title: failure.Title, Message: failure.Message, ResponseCode: failure.ResponseCode, @@ -255,11 +252,21 @@ func setHeaders(headers map[string]string, w http.ResponseWriter) { } } -// logError writes an error record through the instance logger, if any. The -// writer has no request, so the record carries no request context. +// logError writes an error record through the writer's logger. The writer +// has no request, so the record carries no request context. func (writer ResponseWriter) logError(msg string, err error) { - if writer.logger == nil { - return + logger := writer.logger + if logger == nil { + logger = slog.Default() + } + logger.LogAttrs(context.Background(), slog.LevelError, msg, slog.Any("error", err)) +} + +// responseFormatter returns the formatter that builds the writer's 500 body: +// the instance's, or the registered one on the default instance's writer. +func (writer ResponseWriter) responseFormatter() core.APIResponseFormatter { + if writer.formatter == nil { + return responseFormatter } - writer.logger.LogAttrs(context.Background(), slog.LevelError, msg, slog.Any("error", err)) + return writer.formatter } diff --git a/instance_log_test.go b/instance_log_test.go index 40b2972..57a3616 100644 --- a/instance_log_test.go +++ b/instance_log_test.go @@ -12,7 +12,6 @@ import ( "net/http" "net/http/httptest" "os" - "regexp" "slices" "strconv" "strings" @@ -163,8 +162,8 @@ func TestInstanceRedactsQueryCookieAndSession(t *testing.T) { } // TestInstanceURIMaskingAgreesWithTheDefaultInstance checks that an instance -// masks the logged uri exactly as the default instance's REQUEST line does, -// since both use the same redaction helpers, and pins the masked uri. +// masks the logged uri exactly as the default instance does, since both share +// one code path, and pins the masked uri. func TestInstanceURIMaskingAgreesWithTheDefaultInstance(t *testing.T) { tests := []struct{ name, uri, want string }{ {name: "no query", uri: "/tasks", want: "/tasks"}, @@ -187,15 +186,15 @@ func TestInstanceURIMaskingAgreesWithTheDefaultInstance(t *testing.T) { } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - defaultLines := captureDefaultLogLines(t) + defaultBuf := captureDefaultLogger(t) logger, buf := newRecordingLogger() instance := New(WithLogger(logger)) ProcessRequest(okHandler).ServeHTTP(httptest.NewRecorder(), newRawURIRequest(tt.uri)) instance.Handler(ProcessRequest(okHandler)).ServeHTTP(httptest.NewRecorder(), newRawURIRequest(tt.uri)) - if got := defaultLoggedURI(t, *defaultLines); got != tt.want { - t.Fatalf("default instance uri = %q, want %q", got, tt.want) + if got := recordNamed(t, decodeRecords(t, defaultBuf), "request")["uri"]; got != tt.want { + t.Fatalf("default instance uri = %v, want %q", got, tt.want) } if got := recordNamed(t, decodeRecords(t, buf), "request")["uri"]; got != tt.want { t.Fatalf("instance uri = %v, want %q", got, tt.want) @@ -212,26 +211,6 @@ func newRawURIRequest(uri string) *http.Request { return req } -var loggedURIPattern = regexp.MustCompile(`uri=("(?:[^"\\]|\\.)*")`) - -// defaultLoggedURI returns the uri of the default instance's REQUEST line. -func defaultLoggedURI(t *testing.T, lines []string) string { - t.Helper() - for _, line := range lines { - match := loggedURIPattern.FindStringSubmatch(line) - if !strings.HasPrefix(line, "Print: REQUEST ") || match == nil { - continue - } - uri, err := strconv.Unquote(match[1]) - if err != nil { - t.Fatalf("unquoting uri of %q: %v", line, err) - } - return uri - } - t.Fatalf("no REQUEST line in %q", lines) - return "" -} - // TestInstanceRedactsFormParsedBeforeProcessRequest checks that a form // parsed before ProcessRequest is never logged: bodies are not logged, and // query values appear only, masked, in uri. diff --git a/middlewares.go b/middlewares.go index 1ee5435..f2003f2 100644 --- a/middlewares.go +++ b/middlewares.go @@ -265,7 +265,7 @@ func ProcessRequest(next http.HandlerFunc) http.HandlerFunc { rctx.EventID = generateEventID(r.Context(), prefixEventID, r.RequestURI) rctx.AddInfo("proxiedIPAddress", proxiedIPAddress) - a.logRequest(r, rctx.EventID, rctx.RawBody) + a.logRequest(r, rctx.EventID) r = UpdateRequestContext(rctx, r) rctx.Context = r.Context() diff --git a/middlewares_recover_test.go b/middlewares_recover_test.go index c624ed9..af0e2aa 100644 --- a/middlewares_recover_test.go +++ b/middlewares_recover_test.go @@ -1,7 +1,6 @@ package api import ( - "fmt" "net/http" "net/http/httptest" "strings" @@ -9,10 +8,8 @@ import ( ) func TestProcessRequestLogsPanicValueWithoutRequest(t *testing.T) { - previousPrintError := PrintError - var logged string - PrintError = func(args ...interface{}) { logged += fmt.Sprintln(args...) } - defer func() { PrintError = previousPrintError }() + buf := captureDefaultLogger(t) + failOnPackageLoggers(t) handler := ProcessRequest(func(w http.ResponseWriter, r *http.Request) { panic("handler panic value") @@ -23,6 +20,7 @@ func TestProcessRequestLogsPanicValueWithoutRequest(t *testing.T) { res := httptest.NewRecorder() handler.ServeHTTP(res, req) + logged := buf.String() if res.Code != http.StatusInternalServerError { t.Fatalf("expected status 500, got %d", res.Code) diff --git a/response.go b/response.go index 1cb2b45..0cb1e4a 100644 --- a/response.go +++ b/response.go @@ -1,9 +1,6 @@ package api import ( - "bytes" - "encoding/json" - "errors" "log/slog" "net/http" @@ -27,88 +24,15 @@ func getEventID(r *http.Request) string { } // ResponseWriter implementation of core.APIResponseWriter interface. -// The zero value is the default instance's writer, described on Write; New -// binds its logger and formatter to it, so an instance's built-in writer -// logs through the instance logger and builds the 500 body with the -// instance formatter instead. Both send the Content-Type set in the -// formatted Headers (any key case; an empty value counts as unset), else -// application/json; one a handler set on w.Header() is overwritten. +// The zero value is the default instance's writer: it logs through +// slog.Default and builds its 500 body with the formatter registered with +// RegisterNewAPIResponseFormatter. New binds its logger and formatter to it, +// so an instance's built-in writer logs through the instance logger and +// builds the 500 body with the instance formatter instead. Both send the +// Content-Type set in the formatted Headers (any key case; an empty value +// counts as unset), else application/json; one a handler set on w.Header() +// is overwritten. type ResponseWriter struct { - // fromNew is set by New; false is the default instance's v0 behavior. - fromNew bool logger *slog.Logger formatter core.APIResponseFormatter } - -// Write the API response in screen. On the default instance, the body is -// encoded before anything is written. A body that cannot be encoded (e.g. a -// NaN float) is reported through PrintError and answered with 500 and the -// internal server error body, built by the registered response formatter, -// with the response headers kept except the ones that described the failed -// body (see writeEncodeFailure). The error body carries no event ID or -// token, since the request is not available here. If the handler already wrote a status, that -// status stays and the error body is written under it. -// -// http.ErrBodyNotAllowed from writing the body is not reported: Warning and -// Informative default to status 100, which a server sends as informational -// before delivering the body with 200, while the recorder that ProcessRequest -// writes into returns this error. -func (writer ResponseWriter) Write(response *core.ResponseFormatted, w http.ResponseWriter) { - if writer.fromNew { - writer.writeForInstance(response, w) - return - } - var body bytes.Buffer - if err := json.NewEncoder(&body).Encode(response.Body); err != nil { - PrintError(err) - writeEncodeFailure(response.Headers, w) - return - } - writeEncoded(response.Headers, response.HTTPStatusCode, body.Bytes(), w) -} - -// writeEncodeFailure answers 500 with the internal server error body built by -// the registered formatter, labeled with that body's Content-Type. The -// headers that described the failed body (see isBodyHeader) are dropped and -// the others kept, as on an instance. If the formatter returns no body, or it -// cannot be encoded either, it answers 500 with no body and no Content-Type. -func writeEncodeFailure(headers map[string]string, w http.ResponseWriter) { - headers = withoutBodyHeaders(headers) - failure := Error500() - formatted := responseFormatter.Format(core.ResponseData{ - Title: failure.Title, - Message: failure.Message, - ResponseCode: failure.ResponseCode, - HTTPStatusCode: failure.HTTPStatusCode, - ResponseType: ErrorType, - }) - if formatted == nil { - writeBare500(headers, w) - return - } - var body bytes.Buffer - if err := json.NewEncoder(&body).Encode(formatted.Body); err != nil { - PrintError(err) - writeBare500(headers, w) - return - } - if contentType := formattedContentType(formatted.Headers); contentType != "" { - headers["Content-Type"] = contentType - } - writeEncoded(headers, http.StatusInternalServerError, body.Bytes(), w) -} - -func writeEncoded(headers map[string]string, status int, body []byte, w http.ResponseWriter) { - for key := range headers { - w.Header().Set(key, headers[key]) - } - contentType := formattedContentType(headers) - if contentType == "" { - contentType = "application/json" - } - w.Header().Set("Content-Type", contentType) - w.WriteHeader(status) - if _, err := w.Write(body); err != nil && !errors.Is(err, http.ErrBodyNotAllowed) { - PrintError(err) - } -} diff --git a/response_writer_test.go b/response_writer_test.go index aee535a..b423980 100644 --- a/response_writer_test.go +++ b/response_writer_test.go @@ -8,27 +8,19 @@ import ( "net/http" "net/http/httptest" "strings" - "sync" "testing" "github.com/jgolang/api/core" ) func TestResponseWriterAnswers500WhenBodyCannotBeEncoded(t *testing.T) { - previousFatal, previousPrintError := Fatal, PrintError - var fatalCalled bool - var logged string - Fatal = func(...interface{}) { fatalCalled = true } - PrintError = func(args ...interface{}) { logged += fmt.Sprintln(args...) } - defer func() { Fatal, PrintError = previousFatal, previousPrintError }() + buf := captureDefaultLogger(t) + failOnPackageLoggers(t) req := httptest.NewRequest(http.MethodGet, "/ratio", nil) res := httptest.NewRecorder() SuccessWithContent(map[string]float64{"ratio": math.NaN()}).Write(res, req) - if fatalCalled { - t.Fatal("expected Fatal not to be called") - } if res.Code != http.StatusInternalServerError { t.Fatalf("expected status 500, got %d", res.Code) } @@ -44,8 +36,9 @@ func TestResponseWriterAnswers500WhenBodyCannotBeEncoded(t *testing.T) { if header["code"] != wantCode { t.Fatalf("expected code %q, got %#v", wantCode, body) } - if !strings.Contains(logged, "NaN") { - t.Fatalf("expected the encoding error to be logged, got %q", logged) + record := recordNamed(t, decodeRecords(t, buf), "response cannot be encoded") + if !strings.Contains(fmt.Sprint(record["error"]), "NaN") { + t.Fatalf("expected the encoding error to be logged, got %v", record) } } @@ -71,7 +64,7 @@ func TestResponseWriterKeepsStatusAndHeadersOnSuccess(t *testing.T) { // Warning and Informative default to status 100. A real server sends it as an // informational status and delivers the body with 200; the recorder that // ProcessRequest writes into rejects the body with http.ErrBodyNotAllowed, -// which must neither exit the process nor be logged. +// which must neither exit the process nor be logged as an error. func TestDefaultInformationalStatusReachesClientWithoutFatal(t *testing.T) { tests := []struct { name string @@ -84,14 +77,10 @@ func TestDefaultInformationalStatusReachesClientWithoutFatal(t *testing.T) { } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - previousFatal, previousPrintError := Fatal, PrintError - var mu sync.Mutex - var fatalCalled bool - var logged string - Fatal = func(...interface{}) { mu.Lock(); fatalCalled = true; mu.Unlock() } - PrintError = func(args ...interface{}) { mu.Lock(); logged += fmt.Sprintln(args...); mu.Unlock() } + // The server goroutine logs into buf; it is read after server.Close. + buf := captureDefaultLogger(t) + failOnPackageLoggers(t) server := httptest.NewServer(tt.handler) - defer func() { Fatal, PrintError = previousFatal, previousPrintError }() defer server.Close() res, err := http.Get(server.URL + "/tasks") @@ -105,19 +94,16 @@ func TestDefaultInformationalStatusReachesClientWithoutFatal(t *testing.T) { } server.Close() - mu.Lock() - defer mu.Unlock() - if fatalCalled { - t.Fatal("expected Fatal not to be called") - } if res.StatusCode != http.StatusOK { t.Fatalf("expected the client to get status 200, got %d", res.StatusCode) } if !strings.Contains(string(body), `"type":"`+tt.wantType+`"`) { t.Fatalf("expected a %s body, got %q", tt.wantType, body) } - if logged != "" { - t.Fatalf("expected nothing logged, got %q", logged) + for _, record := range decodeRecords(t, buf) { + if record["level"] != "INFO" { + t.Fatalf("expected only the request and response records, got %v", record) + } } }) } @@ -136,13 +122,9 @@ func (errorMarkerFormatter) Format(data core.ResponseData) *core.ResponseFormatt } func TestResponseWriterBuildsFailureWithRegisteredFormatterAndHeaders(t *testing.T) { - previousPrintError := PrintError - PrintError = func(...interface{}) {} + captureDefaultLogger(t) RegisterNewAPIResponseFormatter(errorMarkerFormatter{}) - defer func() { - PrintError = previousPrintError - RegisterNewAPIResponseFormatter(ResponseFormatter{}) - }() + defer RegisterNewAPIResponseFormatter(ResponseFormatter{}) res := httptest.NewRecorder() Success{ @@ -162,9 +144,7 @@ func TestResponseWriterBuildsFailureWithRegisteredFormatterAndHeaders(t *testing } func TestResponseWriterFailureAfterStatusWrittenKeepsEarlierStatus(t *testing.T) { - previousPrintError := PrintError - PrintError = func(...interface{}) {} - defer func() { PrintError = previousPrintError }() + captureDefaultLogger(t) res := httptest.NewRecorder() res.WriteHeader(http.StatusAccepted) @@ -227,13 +207,9 @@ func TestDefaultEncodeFailureHeaders(t *testing.T) { } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - previousPrintError := PrintError - PrintError = func(...interface{}) {} + captureDefaultLogger(t) RegisterNewAPIResponseFormatter(tt.formatter) - t.Cleanup(func() { - PrintError = previousPrintError - RegisterNewAPIResponseFormatter(ResponseFormatter{}) - }) + t.Cleanup(func() { RegisterNewAPIResponseFormatter(ResponseFormatter{}) }) res := httptest.NewRecorder() res.Header().Set("Content-Type", "text/html")