# Logowanie request/response

`@LoggedRequest` pozwala włączyć logowanie żądania i odpowiedzi HTTP dla dowolnego kontrolera lub pojedynczej metody przez dodanie jednej adnotacji. Dane wrażliwe będziemy starali się (dosyć naiwnie) maskować przed zapisaniem do logu.

## Jak używać

Dodaj adnotację na całym kontrolerze:

```
@LoggedRequest
class TestRESTController {
    def show() { ... }
    def update() { ... }
}
```

albo tylko na wybranej metodzie:

```
class SomeRESTController {
    @LoggedRequest
    def update() { ... }
}
```

### Konfiguracja (`application.yml`)

```
logintegra:
  requestLogging:
    enabled: false       # globalny wyłącznik, domyślnie false gdyby klucz zniknął z configu
    maxBodySize: 8192    # maks. liczba znaków treści request/response zapisywana do logu, reszta ucinana
    piiFields: []         # dodatkowe (ponad domyślne) nazwy pól JSON/form do zamaskowania
```

### Gdzie szukać logów

Log leci na logger `logintegra.requestlog`, poziom `INFO`, na standardowy appender `STDOUT` (`grails-app/conf/logback.xml`). Poziom można zmienić bez restartu przez panel admina opisany w [`logback-runtime-conf.md`](<https://docs.logintegra.com/apollo-backend/logback-runtime-conf/index.md>) (`/apollo/logs`, rola `ROLE_SUPER_USER`) - loggera szukaj po nazwie `logintegra.requestlog`.

Przykładowa linia logu):

```
{
  "controller": "someRest",
  "action": "update",
  "httpMethod": "PUT",
  "uri": "/api/transports/123",
  "queryString": null,
  "actor": "jan.kowalski",
  "requestHeaders": { "Authorization": "***REDACTED***", "Content-Type": "application/json" },
  "requestBody": "{\"password\":\"***REDACTED***\",\"name\":\"Jan\"}",
  "responseStatus": 200,
  "responseBody": "{\"id\":123,\"status\":\"OK\"}"
}
```

## Maskowanie danych wrażliwych (PII)

`LogPiiSanitizerService` maskuje wartości pól, których nazwa (bez rozróżniania wielkości liter) pasuje do listy `LogPiiSanitizerService.DEFAULT_PII_FIELDS` rozszerzonej o `logintegra.requestLogging.piiFields` z configu. Działa rekurencyjnie po całym JSON (zagnieżdżone obiekty, tablice) oraz  
po parach `klucz=wartość` w przypadku `application/x-www-form-urlencoded`.

Nagłówki `Authorization`, `Cookie`, `Set-Cookie`, `X-Auth-Token` są maskowane zawsze, niezależnie od configu (`LogPiiSanitizerService.SENSITIVE_HEADERS`).

**Dodanie nowego pola do maskowania:** - jeśli jednorazowo to dopisz nazwę do `logintegra.requestLogging.piiFields` w configu, bez zmiany kodu - jeśli na stałe to dopisz do `LogPiiSanitizerService.DEFAULT_PII_FIELDS` i dodaj przypadek testowy w `LogPiiSanitizerServiceTest`.

Aktualnie ten sanitizer nie maskuje np. danych wrażliwych ukrytych w tekście (np. zdanie w polu `note` zawierające PESEL) bo maskowanie jest po nazwie pola. Body, które nie jest poprawnym JSON-em ani `x-www-form-urlencoded`, jest logowane bez zmian.

## Contributions

Pliki modułu:

| Plik | Rola |
| --- | --- |
| `src/main/groovy/logintegra/utils/marker/LoggedRequest.groovy` | adnotacja |
| `src/main/groovy/logintegra/logging/RequestResponseLoggingFilter.groovy` | TYLKO cache'ujące wrappery + `copyBodyToResponse()` |
| `src/main/groovy/logintegra/logging/CommitAwareResponseWrapper.groovy` | zgodność z `GrailsWebRequest.isRenderView()` / `respond()` |
| `grails-app/controllers/logintegra/RequestResponseLoggingInterceptor.groovy` | kwalifikacja, wyciągnięcie wartości z kontekstu Grailsa (`afterView()`) |
| `src/main/groovy/logintegra/logging/RequestResponseLogEntry.groovy` | DTO przenoszący te wartości do serwisu |
| `grails-app/services/logintegra/logging/RequestResponseLogWriterService.groovy` | budowa i zapis logu (obcinanie, pomijanie content-type'ów, serializacja) |
| `grails-app/services/logintegra/logging/LogPiiSanitizerService.groovy` | maskowanie PII |
| `grails-app/conf/spring/resources.groovy` | rejestracja filtra (kolejność w `RequestResponseLoggingFilter.ORDER`) |
| `grails-app/conf/application.yml` | `logintegra.requestLogging.*` |
| `grails-app/conf/logback.xml` | logger `logintegra.requestlog` |
| `src/test/groovy/logintegra/logging/LogPiiSanitizerServiceTest.groovy` | testy sanitizera |
| `src/test/groovy/logintegra/logging/RequestResponseLogWriterServiceTest.groovy` | testy budowy logu (obcinanie, skip, maskowanie) |

Typowe zmiany:

- **Nowe pole do maskowania na stałe** -\> dopisz do `LogPiiSanitizerService.DEFAULT_PII_FIELDS` + test w `LogPiiSanitizerServiceTest`.
- **Nowy typ treści do obsłużenia** (np. XML) -\> rozszerz `LogPiiSanitizerService.sanitizeBody` o kolejną gałąź na podstawie `contentType`, analogicznie do `sanitizeFormEncodedBody`.
- **Zmiana limitu/rozmiaru logowanego body** -\> to jest konfiguracja (`logintegra.requestLogging.maxBodySize`), nie zmiana kodu.
- **Zmiana kształtu logowanej linii / dodanie nowego pola** -\> `RequestResponseLogEntry` (nowe pole) + `RequestResponseLoggingInterceptor.buildLogEntry()` (skąd je wziąć) + `RequestResponseLogWriterService.buildLogEntry()` (gdzie trafia w JSON-ie) + test w `RequestResponseLogWriterServiceTest`.
- **Nowy endpoint do logowania** -\> dodaj `@LoggedRequest`, nic więcej.
- **Zmiana miejsca zapisu logu** (np. osobny plik zamiast STDOUT) -\> dodaj appender w `grails-app/conf/logback.xml` dla loggera `logintegra.requestlog`.
