> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetusk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP/Fetch Transforms

> Transforms for the `http` and `fetch` module

<Tip>The `fetch` module behaves identically to `http`, with the
only difference being `direction` can only be `outbound` because `fetch` cannot
accept incoming requests. Everything else in this doc applies to both modules
equally.</Tip>

## Matchers

As you have seen in [Basic Concepts](/api-tests/pii-redaction/basic-concepts), matchers tell the transform engine what to act on.

To allow for more precise configuration, matchers are split into two types: common fields and matching fields. There can only be *one* matching field, but there can be many common fields.

### Common fields

Common fields are fields that you don't redact, and are only used for the purpose of finding matching spans.

For common fields, you can supply *zero or more* of the following:

* `direction`: either `inbound` or `outbound`
* `method`: a list of HTTP methods like `GET`
* `pathPattern`: a regexp to match on the URL path
* `host`: a regexp to match on the hostname

### Matching fields

Matching fields are fields that you intend to redact. Only one can be present so that what will be modified is clear.

For matching fields, you can only supply *one* of the following:

* `jsonPath`: a JSONPath expression to match on JSON formatted bodies (e.g. `$.user.password`)
* `queryParam`: the name of a query parameter
* `headerName`: the name of a header
* `urlPath`: if set to true, matches on the entire url path
* `fullBody`: if set to true, matches on the entire body

<Info>The presence of `urlPath` may seem strange given that we have
`pathPattern` but you can use this to redact all paths without having
to provide a `pathPattern`.</Info>

## Actions

Actions specify how to mutate the matching span.
Tusk currently supports these actions:

1. `redact`. This replaces the value with a hash. Accepts a `hashPrefix` field
   if you need some form of identifier.
2. `mask`. This replaces the value with a repeated character `mashChar`
   (defaults to '\*'). Use this for fixed length strings where redact won't work.
3. `replace`. Replaces the string with `replaceWith`. This can be used for
   things like testing tokens, etc.
4. `drop`. Deletes all useful data (body, header, etc.) from the span and mark
   it as dropped. The span isn't deleted entirely so that tests depending on it
   can still get mocked.

## Examples

### Redact header

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "transforms": {
        "http": [
          {
            "matcher": {
              "direction": "outbound",
              "host": "api.stripe.com",
              "headerName": "Authorization"
            },
            "action": {
              "type": "redact"
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    transforms:
      http:
        - matcher:
            direction: outbound
            host: api.stripe.com
            headerName: Authorization
          action:
            type: redact
    ```
  </Tab>
</Tabs>

**Before**: `Authorization: Bearer sk_live_51234567890abcdef...`

**After**: `Authorization: REDACTED_c1d2e3f4a5b6...`

### Mask JSON path

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "transforms": {
        "http": [
          {
            "matcher": {
              "direction": "outbound",
              "host": "payments.example.com",
              "method": ["POST"],
              "jsonPath": "$.customer.creditCard.number"
            },
            "action": {
              "type": "mask",
              "maskChar": "*"
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    transforms:
      http:
        - matcher:
            direction: outbound
            host: payments.example.com
            method:
              - POST
            jsonPath: $.customer.creditCard.number
          action:
            type: mask
            maskChar: "*"
    ```
  </Tab>
</Tabs>

**Before**: `{"customer": {"creditCard": {"number": "4111111111111111"}}}`

**After**: `{"customer": {"creditCard": {"number": "****************"}}}`

### Replace JSON path

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "transforms": {
        "http": [
          {
            "matcher": {
              "direction": "outbound",
              "host": "database.internal.com",
              "jsonPath": "$.auth.password"
            },
            "action": {
              "type": "replace",
              "replaceWith": "test-db-password"
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    transforms:
      http:
        - matcher:
            direction: outbound
            host: database.internal.com
            jsonPath: $.auth.password
          action:
            type: replace
            replaceWith: test-db-password
    ```
  </Tab>
</Tabs>

**Before**: `{"auth": {"username": "dbuser", "password": "prod-secret-123"}}`

**After**: `{"auth": {"username": "dbuser", "password": "test-db-password"}}`

### Redact JSON path

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "transforms": {
        "http": [
          {
            "matcher": {
              "direction": "outbound",
              "host": "api.external-service.com",
              "jsonPath": "$.users[*].email"
            },
            "action": {
              "type": "redact"
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    transforms:
      http:
        - matcher:
            direction: outbound
            host: api.external-service.com
            jsonPath: $.users[*].email
          action:
            type: redact
    ```
  </Tab>
</Tabs>

**Before**: `{"users": [{"id": 123, "email": "user@example.com"}]}`

**After**: `{"users": [{"id": 123, "email": "REDACTED_d1e2f3g4h5i6..."}]}`