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")