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
23 changes: 22 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@ The configuration file is called `setting.json`. All settings can also be set vi
| `listen` | `OCAP_LISTEN` | Server address | `127.0.0.1:5000` |
| `prefixURL` | `OCAP_PREFIXURL` | URL prefix for all routes | `""` |
| `secret` | `OCAP_SECRET` | Shared secret — authenticates record uploads and signs admin session JWTs | *required* |
| `logger` | `OCAP_LOGGER` | Enable request logging to STDOUT | `false` |
| `logger` | `OCAP_LOGGER` | Also write logs to `ocap.log` (they always go to STDOUT) | `false` |
| `logLevel` | `OCAP_LOGLEVEL` | Minimum log level: `debug`, `info`, `warn`, `error`. Healthcheck requests are logged at `debug` | `info` |

### Paths

Expand Down Expand Up @@ -243,6 +244,26 @@ When `allowedOrigins` is empty the server responds with `Access-Control-Allow-Or
}
```

### Reverse Proxy

Behind a reverse proxy every request comes from the proxy's address. To log the client's address instead, list the proxies the server should trust. Forwarding headers are read only from requests whose direct peer is one of them; by default no proxy is trusted and headers are ignored.

| Setting | Env Var | Description | Default |
|---------|---------|-------------|---------|
| `trustedProxies` | `OCAP_TRUSTEDPROXIES` | IPs or CIDR ranges of trusted reverse proxies. Comma-separated in env var. | `[]` (trust none) |
| `remoteIPHeaders` | `OCAP_REMOTEIPHEADERS` | Headers holding the client address, tried in order. Comma-separated in env var. | `["X-Forwarded-For", "X-Real-IP"]` |

`X-Forwarded-For` is read right to left: trusted proxies are skipped and the first other address is the client, since entries further left can be sent by the client itself. The access log and the handlers then see the client in `remote_addr`.

```json
"trustedProxies": ["172.18.0.0/16"]
```

**Cloudflare in front of another proxy** (e.g. Cloudflare → Traefik → OCAP): only the direct peer (Traefik) is checked against `trustedProxies`, so a header that proxy merely passes on is only as trustworthy as whoever reached it.

- Recommended: keep `X-Forwarded-For`, let the proxy pass it on (Traefik: `forwardedHeaders.trustedIPs` with [Cloudflare's ranges](https://www.cloudflare.com/ips/)) and list both the proxy and Cloudflare's ranges in `trustedProxies`. Every hop appends its peer to the chain, so a client that bypasses Cloudflare ends up as the first untrusted entry and is logged as itself.
- Simpler: `"remoteIPHeaders": ["CF-Connecting-IP"]` with only the proxy in `trustedProxies`. This header holds a single address that the proxy passes on unchecked, so let only Cloudflare reach the proxy (firewall), otherwise a client that bypasses Cloudflare can set it itself.

## Large Recording Support

### Overview
Expand Down
22 changes: 21 additions & 1 deletion cmd/ocap-webserver/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import (
"log/slog"
"os"
"os/signal"
"strings"
"syscall"
"time"

Expand Down Expand Up @@ -49,9 +50,20 @@ func app() error {
}

// Set up slog with JSON handler for consistent logging
logHandler := slog.NewJSONHandler(logOutput, nil)
logLevel, err := setting.SlogLevel()
if err != nil {
return err
}
logHandler := slog.NewJSONHandler(logOutput, &slog.HandlerOptions{Level: logLevel})
slog.SetDefault(slog.New(logHandler))

trustedProxies, err := server.ParseTrustedProxies(setting.TrustedProxies)
if err != nil {
return err
}
// Docker polls the healthcheck every 30s; keep it out of info-level logs.
healthcheckPath := strings.TrimRight(setting.PrefixURL, "/") + "/api/healthcheck"

operation, err := server.NewRepoOperationWithDataDir(setting.DB, setting.Data)
if err != nil {
return fmt.Errorf("operation: %w", err)
Expand All @@ -70,6 +82,14 @@ func app() error {
s := fuego.NewServer(
fuego.WithAddr(setting.Listen),
fuego.WithLogHandler(logHandler),
// Replaced by server.AccessLogMiddleware.
fuego.WithLoggingMiddleware(fuego.LoggingConfig{DisableRequest: true, DisableResponse: true}),
// Each global middleware wraps the ones before it, so RealIP runs
// first and the access log and handlers see the client address.
fuego.WithGlobalMiddlewares(
server.AccessLogMiddleware(healthcheckPath),
server.RealIPMiddleware(trustedProxies, setting.RemoteIPHeaders),
),
fuego.WithoutAutoGroupTags(),
fuego.WithSecurity(server.OpenAPISecuritySchemes),
fuego.WithEngineOptions(
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ require (
github.com/getkin/kin-openapi v0.153.0
github.com/go-fuego/fuego v0.21.0
github.com/golang-jwt/jwt/v5 v5.3.1
github.com/google/uuid v1.6.0
github.com/gorilla/websocket v1.5.3
github.com/klauspost/compress v1.20.4
github.com/mattn/go-sqlite3 v1.14.53
Expand All @@ -27,7 +28,6 @@ require (
github.com/go-playground/universal-translator v0.18.1 // indirect
github.com/go-playground/validator/v10 v10.30.4 // indirect
github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/gorilla/schema v1.4.1 // indirect
github.com/leodido/go-urn v1.5.0 // indirect
github.com/pelletier/go-toml/v2 v2.4.3 // indirect
Expand Down
110 changes: 110 additions & 0 deletions internal/server/accesslog.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
package server

import (
"bufio"
"log/slog"
"net"
"net/http"
"slices"
"time"

"github.com/google/uuid"
)

// accessLogWriter records the response status for the access log.
type accessLogWriter struct {
http.ResponseWriter
status int
hijacked bool
}

func (w *accessLogWriter) WriteHeader(code int) {
if w.status == 0 {
w.status = code
}
w.ResponseWriter.WriteHeader(code)
}

func (w *accessLogWriter) Write(b []byte) (int, error) {
if w.status == 0 {
w.status = http.StatusOK
}
return w.ResponseWriter.Write(b)
}

func (w *accessLogWriter) Flush() {
if f, ok := w.ResponseWriter.(http.Flusher); ok {
f.Flush()
}
}

func (w *accessLogWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
h, ok := w.ResponseWriter.(http.Hijacker)
if !ok {
return nil, nil, http.ErrNotSupported
}
conn, rw, err := h.Hijack()
if err == nil {
w.hijacked = true
}
return conn, rw, err
}

// Unwrap lets http.ResponseController reach the underlying writer.
func (w *accessLogWriter) Unwrap() http.ResponseWriter {
return w.ResponseWriter
}

func (w *accessLogWriter) statusCode() int {
switch {
case w.hijacked:
return http.StatusSwitchingProtocols
case w.status == 0:
return http.StatusOK
}
return w.status
}

// AccessLogMiddleware logs every request: "incoming request" at debug level
// and "outgoing response" at info level, or at debug level for quietPaths
// (such as the healthcheck polled by Docker). It sets X-Request-ID, keeping
// the one the client sent.
func AccessLogMiddleware(quietPaths ...string) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()

requestID := r.Header.Get("X-Request-ID")
if requestID == "" {
requestID = uuid.NewString()
}
w.Header().Set("X-Request-ID", requestID)

ctx := r.Context()
slog.DebugContext(ctx, "incoming request",
"method", r.Method,
"path", r.URL.Path,
"request_id", requestID,
"remote_addr", r.RemoteAddr,
"user_agent", r.UserAgent(),
)

lw := &accessLogWriter{ResponseWriter: w}
next.ServeHTTP(lw, r)

level := slog.LevelInfo
if slices.Contains(quietPaths, r.URL.Path) {
level = slog.LevelDebug
}
attrs := []any{
"status_code", lw.statusCode(),
"method", r.Method,
"path", r.URL.Path,
"duration_ms", time.Since(start).Milliseconds(),
"request_id", requestID,
"remote_addr", r.RemoteAddr,
}
slog.Log(ctx, level, "outgoing response", attrs...)
})
}
}
104 changes: 104 additions & 0 deletions internal/server/accesslog_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
package server

import (
"bytes"
"encoding/json"
"log/slog"
"maps"
"net/http"
"net/http/httptest"
"strings"
"testing"

"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

func captureLogs(t *testing.T, level slog.Level) *bytes.Buffer {
t.Helper()
var buf bytes.Buffer
prev := slog.Default()
slog.SetDefault(slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{Level: level})))
t.Cleanup(func() { slog.SetDefault(prev) })
return &buf
}

func logEntries(t *testing.T, buf *bytes.Buffer) []map[string]any {
t.Helper()
var entries []map[string]any
for line := range strings.Lines(buf.String()) {
var e map[string]any
require.NoError(t, json.Unmarshal([]byte(line), &e))
entries = append(entries, e)
}
return entries
}

func TestAccessLogMiddleware(t *testing.T) {
trusted, err := ParseTrustedProxies([]string{"172.18.0.0/16"})
require.NoError(t, err)
handler := AccessLogMiddleware("/api/healthcheck")(
http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/missing" {
http.NotFound(w, r)
return
}
w.Write([]byte("ok"))
}),
)
// Same order as main: RealIP wraps the access log.
handler = RealIPMiddleware(trusted, nil)(handler)

serve := func(path string, header http.Header) *httptest.ResponseRecorder {
req := httptest.NewRequest(http.MethodGet, path, nil)
req.RemoteAddr = "172.18.0.2:4000"
maps.Copy(req.Header, header)
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)
return rec
}

t.Run("info logs response with client address", func(t *testing.T) {
buf := captureLogs(t, slog.LevelInfo)
rec := serve("/missing", http.Header{"X-Forwarded-For": {"1.2.3.4"}})

entries := logEntries(t, buf)
require.Len(t, entries, 1)
e := entries[0]
assert.Equal(t, "outgoing response", e["msg"])
assert.Equal(t, "INFO", e["level"])
assert.EqualValues(t, http.StatusNotFound, e["status_code"])
assert.Equal(t, "/missing", e["path"])
assert.Equal(t, "1.2.3.4", e["remote_addr"])
assert.NotEmpty(t, e["request_id"])
assert.Equal(t, e["request_id"], rec.Header().Get("X-Request-ID"))
})

t.Run("healthcheck is hidden at info", func(t *testing.T) {
buf := captureLogs(t, slog.LevelInfo)
serve("/api/healthcheck", nil)
assert.Empty(t, buf.String())
})

t.Run("healthcheck is logged at debug", func(t *testing.T) {
buf := captureLogs(t, slog.LevelDebug)
rec := serve("/api/healthcheck", http.Header{"X-Request-Id": {"req-1"}})

entries := logEntries(t, buf)
require.Len(t, entries, 2)
assert.Equal(t, "incoming request", entries[0]["msg"])
assert.Equal(t, "outgoing response", entries[1]["msg"])
assert.Equal(t, "DEBUG", entries[1]["level"])
assert.EqualValues(t, http.StatusOK, entries[1]["status_code"])
assert.Equal(t, "172.18.0.2:4000", entries[1]["remote_addr"])
assert.Equal(t, "req-1", rec.Header().Get("X-Request-ID"))
})
}

func TestAccessLogWriter_ResponseController(t *testing.T) {
rec := httptest.NewRecorder()
w := &accessLogWriter{ResponseWriter: rec}
require.NoError(t, http.NewResponseController(w).Flush())
assert.True(t, rec.Flushed)
assert.Equal(t, http.StatusOK, w.statusCode())
}
Loading
Loading