Actions

Action Execution Rules

• Actions execute in declaration order.
• Termination is explicit by command semantics (not inferred from status changes).
• Commands are internally split by phase:
  • PhasePre commands run in pre.
  • PhasePost commands run in post.
  • PhasePre|PhasePost can happen in nested/compound bodies.
• If a pre command terminates, later pre commands are skipped.
• Post-only commands can still run in post phase.
• status/resp_header matcher rules are always evaluated in post phase.

Available Actions

middleware

A middleware <name> { ... } action runs the request phase of a built-in or composed middleware at that point in rule execution. It continues to the next action when the middleware permits the request. If the middleware handles the request and stops the chain, later actions and the rule fallback do not run.

Only middleware with a request phase is supported. Response-only middleware, such as ModifyResponse, is rejected when the rules are loaded. The name in the block header selects the middleware. The block contains that middleware's configuration properties and may include nested lists and mappings.

Use this action only in request-phase rules and action blocks. A status or resp_header matcher is evaluated after the response is available. A nested action block containing response-phase actions is also scheduled after the response. Both cases are too late for request middleware and are rejected.

default {
  middleware CloudflareRealIP {
  }
}

To configure middleware properties directly in a rule:

default {
  middleware RealIP {
    header: CF-Connecting-IP
    from:
      - 173.245.48.0/20
  }
}

Named Option Blocks

Every action can also be written as a command block. Its header contains the command name followed by any header arguments owned by that command. The YAML-like property body is also defined and validated by the command. For scalar commands, the property names correspond to the arguments shown in the table above.

path /api {
  rewrite {
    from: /api
    to: /backend
  }

  notify {
    level: info
    provider: ntfy
    title: API request
    body: "$req_method $req_url $status_code"
  }
}

Rules for command blocks:

• Each command owns its header arguments and accepted property shapes.
• Scalar command blocks do not take header arguments. All declared properties must be present.
• Unknown or duplicate property names are rejected.
• Scalar property values must be strings, numbers, booleans, or null unless the command accepts structured data. Middleware configuration, for example, may contain nested lists and mappings.

log example

log info /dev/stdout "$req_method $req_url $status_code"

notify example

notify info ntfy "Request received" "$req_method $status_code"

Equivalent named-option form:

notify {
  level: info
  provider: ntfy
  title: Request received
  body: "$req_method $status_code"
}

handle example

path glob("/api/v1/*") {
  handle api
}

Use handle when the target is an HTTP handler already registered inside GoDoxy itself. For external services, keep using proxy.

*log/notify run in pre or post depending on variables used in template (for example $status_code requires post phase).

Template Variables

Template variables can be used in error, log, notify, set, add, body, and resp_body commands. Variables are expanded at runtime using the syntax $variable_name or $function_name(args).

Static Variables

Static variables provide information about the request, response, and upstream service.

Dynamic Variables (Functions)

Dynamic variables accept arguments and can extract specific values from headers, cookies, query parameters, and form data.

Functions support composition: the result of one function can be passed as the argument to another. For example:

# Redact the Authorization header value in logs
log info /dev/stdout "Auth: $redacted($header(Authorization))"

Request Headers: $header(name) or $header(name, index)

Extract header values from the request.

• Arguments:

  • name (required): Header name (case-sensitive)
  • index (optional): Index in the header value list (default: 0)

• Example:

  • $header(User-Agent) → Mozilla/5.0...
  • $header(Accept, 0) → text/html

Response Headers: $resp_header(name) or $resp_header(name, index)

Extract header values from the response.

• Arguments:

  • name (required): Header name (case-sensitive)
  • index (optional): Index in the header value list (default: 0)

• Example:

  • $resp_header(Content-Type) → application/json
  • $resp_header(Set-Cookie, 0) → session_id=abc123

Cookies: $cookie(name) or $cookie(name, index)

Extract cookie values from the request.

• Arguments:

  • name (required): Cookie name
  • index (optional): Index in the cookie value list (default: 0)

• Example:

  • $cookie(session_id) → abc123
  • $cookie(preferences, 0) → dark_mode

Query Parameters: $arg(name) or $arg(name, index)

Extract query parameter values.

• Arguments:

  • name (required): Parameter name
  • index (optional): Index in the parameter value list (default: 0)

• Example:

  • $arg(page) → 1
  • $arg(filter, 0) → active

Form Fields: $form(name) or $form(name, index)

Extract form field values with query parameter fallback. Searches in these sources (from req.Form):

• POST/PUT/PATCH form body (application/x-www-form-urlencoded and multipart/form-data)

• Query parameters

• Arguments:

  • name (required): Field name
  • index (optional): Index in the field value list (default: 0)

• Example:

  • $form(username) → john_doe
  • $form(tags, 1) → backend (second tag)

POST Form Fields: $postform(name) or $postform(name, index)

Extract form field values from POST/PUT/PATCH request bodies only (no query parameter fallback). Only matches application/x-www-form-urlencoded format.

• Arguments:

  • name (required): Field name
  • index (optional): Index in the field value list (default: 0)

• Example:

  • $postform(action) → matches only form field, not query parameter

Redact: $redacted(value)

Mask a sensitive value, showing only the first 2 and last 2 characters with asterisks in between.

• Arguments:

  • value (required): A literal string or the result of another dynamic variable function

• Example:

  • $redacted(mysecrettoken) → my*********en
  • $redacted($header(Authorization)) → Be************ne (redacts the Authorization header value)
  • $redacted($cookie(session_id)) → ab****23

Variable Examples

Complete examples showing how to use variables in different commands:

# Logging with request and response information
log info /dev/stdout "Method=$req_method Path=$req_path Status=$status_code"

# Logging with headers (redacting sensitive values)
log info /dev/stdout "User-Agent=$header(User-Agent) Auth=$redacted($header(Authorization))"

# Logging with response headers
log info /dev/stdout "Content-Type=$resp_header(Content-Type) Content-Length=$resp_content_length"

# Notifications with request context
notify info ntfy "New request" "From $remote_host to $req_host at $req_path"

# Setting headers with upstream information
set header X-Upstream-URL $upstream_url
set header X-Request-Path $req_path

# Body modifications with request info
set body "Status: $status_code for $req_method $req_path"

# Response body with request and response info
set resp_body "Request: $req_method $req_url\nResponse: $status_code"