Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ func main() {
- 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; 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.
- stores the request context, replaces `r.Body` with the endpoint content, and answers 500 if the handler panics (a panic with `http.ErrAbortHandler` is re-panicked, so `net/http` aborts the response).

Use `api.MiddlewaresChain(...)` to compose it with your own middlewares. `api.AddSkipPath(api.GenSkipPath(method, path), true)` makes it pass a route through untouched.
3. **The handler** reads the content, then writes one [response](#responses) or [error](#writing-errors).
Expand Down Expand Up @@ -264,7 +264,7 @@ 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`) 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 panic record always has `panic_type`, the Go type of the value (`string`, `*errors.errorString`, `runtime.boundsError`); its `panic` is the value only for a `runtime.Error` (nil map write, index out of range), which carries no request data, and `[REDACTED]` for any other value, which may. 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 with a sensitive name, query values in `uri` and in other header values (after each `?`), and the user information of the `uri` and of URL-valued headers 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.
`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`) and a response that cannot be encoded are error records with an `error` or `panic` attribute; a panic with `http.ErrAbortHandler`, plain or wrapped, is a `handler aborted` debug record and is re-panicked as the plain `http.ErrAbortHandler`, so `net/http` aborts the response without logging it; nothing is written and there is no `response` record (nor after any other recovered panic). A panic record always has `panic_type`, the Go type of the value (`string`, `*errors.errorString`, `runtime.boundsError`); its `panic` is the value only for a `runtime.Error` (nil map write, index out of range), which carries no request data, and `[REDACTED]` for any other value, which may. 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; so is a nil formatted response (a custom formatter that returned nil), logged as `response cannot be written` with `error` `nil formatted response`; 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 with a sensitive name, query values in `uri` and in other header values (after each `?`), and the user information of the `uri` and of URL-valued headers 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.

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.

Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0001-v1-instance-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ sequenceDiagram
- An instance without `WithLogger` writes no logs.
- With the built-in writer, an instance never calls `Fatal` and never exits: a response that cannot be encoded is logged at error level through the instance logger. Since v0.11.0 (#46) the default instance does not call `Fatal` either: it reports the failure through `PrintError` and answers 500. *(Superseded by Amendment 1: the default instance logs it through `slog.Default`, not `PrintError`.)*
- `WithSensitiveLogKeys(keys...)` adds keys to the default list; it cannot remove a default key (security defaults are not weakened).
- As landed in 5.5: `ProcessRequest` writes two info records, `request` (`event_id`, `method`, `uri`, `headers`) and `response` (`event_id`, `method`, `uri`, `status`, `status_text`, `duration_ms`). Errors met while serving a request (a rejected body in `ProcessRequest`/`RequestBody`, a failed `Get*Value*`/`UnmarshalBody` helper) are error records with an `error` attribute; a `Get*Value*` record adds the name as `key` and, for a sensitive name, gives only the kind of error (`invalid syntax`, `value out of range`, `invalid value`), never the value. A recovered panic is a `panic recovered` error record with exactly the panic value and `event_id`, never a dump of the request; a panic with `http.ErrAbortHandler` is a `handler aborted` debug record. *(Amended in v1.1.1: the record carries `panic_type`, and `panic` is the value only for a `runtime.Error`, `[REDACTED]` otherwise, since an opaque value cannot be masked by key; header values are masked after each `?` and, when they carry a URL, in their user information, as `uri` is.)* An instance's key list is the built-in default list (the shipped value of `SensitiveLogKeys`, which has `cookie` and `session` since v0.11.0) plus its added keys; changes to the `SensitiveLogKeys` variable never reach an instance; added keys are lowercased and blank ones ignored; matching stays v0's case-insensitive substring match. The `uri` is masked with the default instance's helpers from v0.11.0 (#60), so both agree: query values by key with the literal `[REDACTED]` (a masked value runs to the next `&`, a key that cannot be unescaped is masked) and the user information of an absolute-form, `//host` or CONNECT authority-form target up to the last `@`; path segments are not. Bodies and the parsed form are never logged (no option, per section 5; query values still appear in `uri`). The built-in writer of an instance encodes before writing: a body that cannot be encoded is logged as `response cannot be encoded` and answered with 500 and the instance formatter's `Error500()` body (bare 500, with the response headers, if the formatter returns nil or that fails too); `http.ErrBodyNotAllowed` is not logged; the `Content-Type` comes only from the formatted headers (`application/json` when they set none), so one a handler set on `w.Header()` never labels the body; the encode-failure 500 drops the failed response's body headers (`Content-Type`, `Content-Encoding`, `Content-Length`, `Content-Range`, `Content-Disposition`, `Content-Language`, `Content-Location`, `ETag`, `Last-Modified`) and uses the error body's `Content-Type`; since 5.6 the default instance's writer also takes a `Content-Type` set in `Headers`, else `application/json` (section 8). `core.APIResponseWriter.Write` receives no request, so the writer's `response cannot be encoded`/`response cannot be written` records carry no request context or `event_id`. A custom writer, including a type that embeds `ResponseWriter`, is used as given and keeps the default instance's behavior. An instance never reads `Print`, `PrintError`, `Fatal` or `SensitiveLogKeys`, now deprecated with `LogRequest`, `LogResponse` and `LogResponseWithDuration`. *(Superseded by Amendment 1: the default instance writes these same records through `slog.Default`, and a type that embeds `ResponseWriter` logs through `slog.Default` with the registered formatter.)*
- As landed in 5.5: `ProcessRequest` writes two info records, `request` (`event_id`, `method`, `uri`, `headers`) and `response` (`event_id`, `method`, `uri`, `status`, `status_text`, `duration_ms`). Errors met while serving a request (a rejected body in `ProcessRequest`/`RequestBody`, a failed `Get*Value*`/`UnmarshalBody` helper) are error records with an `error` attribute; a `Get*Value*` record adds the name as `key` and, for a sensitive name, gives only the kind of error (`invalid syntax`, `value out of range`, `invalid value`), never the value. A recovered panic is a `panic recovered` error record with exactly the panic value and `event_id`, never a dump of the request; a panic with `http.ErrAbortHandler` is a `handler aborted` debug record. *(Amended in v1.1.1: the record carries `panic_type`, and `panic` is the value only for a `runtime.Error`, `[REDACTED]` otherwise, since an opaque value cannot be masked by key; header values are masked after each `?` and, when they carry a URL, in their user information, as `uri` is; a panic with `http.ErrAbortHandler`, plain or wrapped, is re-panicked as the plain `http.ErrAbortHandler` after its `handler aborted` record (a wrapped value would be logged by `net/http` with its text and a stack), writing nothing, so `net/http` aborts the response as it does without `ProcessRequest`; the built-in writer answers a nil formatted response like an encode failure and logs `response cannot be written` with `error` `nil formatted response`.)* An instance's key list is the built-in default list (the shipped value of `SensitiveLogKeys`, which has `cookie` and `session` since v0.11.0) plus its added keys; changes to the `SensitiveLogKeys` variable never reach an instance; added keys are lowercased and blank ones ignored; matching stays v0's case-insensitive substring match. The `uri` is masked with the default instance's helpers from v0.11.0 (#60), so both agree: query values by key with the literal `[REDACTED]` (a masked value runs to the next `&`, a key that cannot be unescaped is masked) and the user information of an absolute-form, `//host` or CONNECT authority-form target up to the last `@`; path segments are not. Bodies and the parsed form are never logged (no option, per section 5; query values still appear in `uri`). The built-in writer of an instance encodes before writing: a body that cannot be encoded is logged as `response cannot be encoded` and answered with 500 and the instance formatter's `Error500()` body (bare 500, with the response headers, if the formatter returns nil or that fails too); `http.ErrBodyNotAllowed` is not logged; the `Content-Type` comes only from the formatted headers (`application/json` when they set none), so one a handler set on `w.Header()` never labels the body; the encode-failure 500 drops the failed response's body headers (`Content-Type`, `Content-Encoding`, `Content-Length`, `Content-Range`, `Content-Disposition`, `Content-Language`, `Content-Location`, `ETag`, `Last-Modified`) and uses the error body's `Content-Type`; since 5.6 the default instance's writer also takes a `Content-Type` set in `Headers`, else `application/json` (section 8). `core.APIResponseWriter.Write` receives no request, so the writer's `response cannot be encoded`/`response cannot be written` records carry no request context or `event_id`. A custom writer, including a type that embeds `ResponseWriter`, is used as given and keeps the default instance's behavior. An instance never reads `Print`, `PrintError`, `Fatal` or `SensitiveLogKeys`, now deprecated with `LogRequest`, `LogResponse` and `LogResponseWithDuration`. *(Superseded by Amendment 1: the default instance writes these same records through `slog.Default`, and a type that embeds `ResponseWriter` logs through `slog.Default` with the registered formatter.)*

### 7. Errors: kind-to-status override and error hook (API-01)

Expand Down
47 changes: 25 additions & 22 deletions instance.go
Original file line number Diff line number Diff line change
Expand Up @@ -245,33 +245,35 @@ const maxErrorStatus = 599
// is not recovered: it propagates out of WriteError with nothing written.
// Under ProcessRequest it answers 500 and is logged, with the panic type,
// through the instance's WithLogger logger; nothing is logged without one.
// fn is shared by all
// requests the instance serves and may run concurrently, so it must be safe
// for concurrent use. A later WithErrorHook replaces an earlier one, and nil
// means no hook.
// fn is shared by all requests the instance serves and may run concurrently,
// so it must be safe for concurrent use. A later WithErrorHook replaces an
// earlier one, and nil means no hook.
func WithErrorHook(fn func(r *http.Request, err error, status int)) Option {
return func(o *options) {
o.errorHook = fn
}
}

// WithLogger makes the instance log through logger: ProcessRequest writes a
// "request" and a "response" info record per request, and errors met while
// "request" info record per request and a "response" info record per
// response the handler completes (none after a recovered panic, although its
// 500 is still written), and errors met while
// serving one (a rejected body, a failed Get*Value* helper, a recovered
// panic, a response that cannot be encoded) are written as error records.
// Request and response bodies and the parsed form are never logged. Header
// and query values whose key is sensitive (see WithSensitiveLogKeys) are
// masked, as is the user information of an absolute-form URI; other header
// values have the query values after each "?" masked the same way, and the
// user information too when they carry a URL; a failed Get*Value* helper logs the name as "key" and, for a sensitive name, only
// the kind of error, never the value. A recovered panic logs its Go type as
// "panic_type" and its value only for a runtime.Error. A panic with
// http.ErrAbortHandler is a "handler aborted" debug record instead of an
// error record.
// The built-in writer's records carry no request context or event_id, since
// core.APIResponseWriter.Write receives no request.
// Without it, or with nil, the instance writes no logs. A later WithLogger
// replaces an earlier one.
// panic, a response that cannot be encoded or written) are written as error
// records. Request and response bodies and the parsed form are never
// logged. Header and query values whose key is sensitive (see
// WithSensitiveLogKeys) are masked, as is the user information of an
// absolute-form URI; other header values have the query values after each
// "?" masked the same way, and the user information too when they carry a
// URL; a failed Get*Value* helper logs the name as "key" and, for a
// sensitive name, only the kind of error, never the value. A recovered
// panic logs its Go type as "panic_type" and its value only for a
// runtime.Error. A panic with http.ErrAbortHandler is a "handler aborted"
// debug record instead of an error record, and ProcessRequest re-panics it
// so net/http aborts the response. The built-in writer's records carry no
// request context or event_id, since core.APIResponseWriter.Write receives
// no request. Without it, or with nil, the instance writes no logs. A later
// WithLogger replaces an earlier one.
func WithLogger(logger *slog.Logger) Option {
return func(o *options) {
o.logger = logger
Expand Down Expand Up @@ -351,9 +353,10 @@ func WithResponseFormatter(formatter core.APIResponseFormatter) Option {
// WithResponseWriter sets the writer that sends the instance's formatted
// responses. The built-in ResponseWriter, as a value, a pointer or a nil
// interface value, is bound to the instance's logger and formatter: it logs a
// body that cannot be encoded through the instance logger and answers 500
// 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
// body that cannot be encoded, or a nil formatted response, through the
// instance logger and answers 500 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 (slog.Default and the registered formatter).
func WithResponseWriter(writer core.APIResponseWriter) Option {
Expand Down
Loading
Loading