Class EdgeToken

java.lang.Object
org.frontcache.core.EdgeToken

public class EdgeToken extends Object
The front-cache.edge-token - how a second-layer node tells a request from its own edge apart from one that reached it directly. In a chained deployment (browser -> edge -> second layer -> app) the second layer is usually reachable some other way too: a public origin hostname the edge itself needs, a CDN tunnel, a bare IP. Traffic that takes that route skips every guard rule and rate limit on the edge, and nothing on the wire said so - the edge's own markers are either forgeable (x-frontcache-request-id, X-Forwarded-Host) or absent on some of its calls (FC_BypassCache sends no request-id).

One token per chain, sent and accepted by every node

A node with a token SENDS it on every origin call it makes (stamp(HttpRequest, String) - and only to the origin host, see there) and ACCEPTS it on every request it receives (isValid(HttpServletRequest)). Every node of the chain carries the same value, so there is one setting and no notion of direction - which is what makes a filter-mode node's own include fetch, which re-enters the same node over HTTP, a non-event: it is an origin call by a node with a token, so it carries one. Per-edge tokens were considered and dropped: one token per chain is enough, and a compromised edge is answered by rotating it (.previous keeps both values accepted while the fleet is re-configured).

Not the api-key

The api-key authorizes management writes. Sending it on every origin call, through every CDN hop and into the origin app's request headers, would widen the exposure of a write credential for no gain. A separate secret has a separate blast radius and its own rotation.

Where it is enforced

Nowhere by itself. isValid(HttpServletRequest) is computed once per request in FrontCacheEngine.init() and exposed to guard-rules.conf as the edge-token predicate, so enforcement is an ordinary guard rule with dry-run, hit counters, the console's Guard tab and the failed-requests log:
  direct-get   | !edge-token ; method:GET | redirect:301 https://www.example.com${uri}${query}
  direct-other | !edge-token              | reject:403

Never relayed

FCUtils.isIncludedHeader drops an inbound FCHeaders.X_FRONTCACHE_EDGE_TOKEN, and stamp(HttpRequest, String) SETS the header rather than adding it, so a node only ever sends its own value and a client's copy goes no further than the first Frontcache it reaches. In filter mode the app sees the raw servlet request, header included - nothing a filter can strip without wrapping the request.

Read per call

Like ApiKey: a property read is cheap, and it keeps a test or a future config reload from holding on to a stale value.
  • Field Details

    • EDGE_TOKEN_PROPERTY

      public static final String EDGE_TOKEN_PROPERTY
      Sent on every origin call, accepted on every inbound request.
      See Also:
    • PREVIOUS_EDGE_TOKEN_PROPERTY

      public static final String PREVIOUS_EDGE_TOKEN_PROPERTY
      Accepted, never sent - the overlap that lets a fleet rotate without a flag day.
      See Also:
  • Method Details

    • configured

      public static String configured()
      Returns:
      the token this node sends and accepts, or "" when it has none
    • previous

      public static String previous()
      Returns:
      the token accepted during a rotation, or ""
    • isConfigured

      public static boolean isConfigured()
      Returns:
      true when this node has an edge token. Without one it sends nothing, and a guard rule naming edge-token is refused at load - !edge-token would otherwise match every request.
    • isValid

      public static boolean isValid(jakarta.servlet.http.HttpServletRequest request)
      Parameters:
      request - the inbound request
      Returns:
      true when the request carries this node's token, or the previous one. Always false on a node with no token: an unconfigured node has nothing to compare against, and "valid" must never be the answer to "I cannot tell".
    • stamp

      public static void stamp(org.apache.hc.core5.http.HttpRequest request, String targetHost)
      Puts this node's token on an outgoing request - but only one addressed to front-cache.origin-host. Replaces any value already there, so an inbound copy can never ride along. Does nothing on a node with no token.

      Why the host check

      The commands that call this do not only ever talk to the origin. With include-fetch-target=edge an absolute <fc:include url="https://other.example/…"> is fetched from where it points, and a fallbacks.conf init URL can name any host. A shared secret that went wherever page markup or a config line sent it would be a secret in somebody else's access log. Everything the token exists for - page misses, origin-mode include fetches (rebased onto the origin by FCUtils.rebaseURL), bypassed calls - is addressed to the origin host, so that is the whole of where it goes. An edge-mode include comes back through this node's own front door and gets the token on that request's origin call instead.
      Parameters:
      request - the request about to be executed
      targetHost - the host it is addressed to (HttpHost.getHostName())
    • logConfiguration

      public static void logConfiguration(org.slf4j.Logger logger)
      Says once, at startup, what this node does with the token - and never what the token is.