Home / User Guide / Result Caching

Result Caching

Why this exists

Dispatchers re-submit the same plan after a UI refresh or a double-click. Clients retry after a network timeout without knowing the first attempt already succeeded. Two callers submit an identical scenario within seconds of each other. Each of these, without caching, re-runs the full solver — seconds to tens of seconds of CPU time — to produce an answer that was already computed. The result cache recognizes an identical request and returns the previously-computed answer instead of solving again.

What counts as "identical"

Every cacheable request is reduced to a single fingerprint, a SHA-256 hash of the request body serialized in a canonical form (sorted keys, no incidental whitespace) combined with the running application's version. Two requests produce the same fingerprint only if their JSON bodies are equivalent (field order and formatting don't matter) and they were served by the same application version.

That version component matters: it is set in CI to the deployed build's commit SHA, so every new deploy invalidates every prior cache entry implicitly. There's no explicit cache-flush step, and therefore no way to accidentally forget one — old entries just become unreachable and expire on their own. This guarantees a code change that alters what the "correct" answer is for a given input can never serve a stale, pre-fix result.

Recurring jobs and fingerprinting

If the recurring-jobs feature is enabled and your request opts in, tenant-specific recurring-pattern jobs may be silently merged into the request before it's solved. Two textually identical raw requests submitted at different times can therefore expand into different actual solver input, depending on which recurring patterns are active for your tenant at request time.

The fingerprint is computed after that injection, on the request the solver actually receives — not on the raw body you sent. This is correct by construction: the cache key reflects what was really solved, so an identical expanded request is guaranteed to be an identical problem, and a request that differs only in what got injected is guaranteed to produce a different key.

Time-to-live

Cached results expire after RESULT_CACHE_TTL_SECONDS (default 3600, one hour). This is a middle ground: long enough to catch a dispatcher re-submitting a slightly later variant of the same scenario, short enough that stale real-world conditions — traffic, vehicle availability, a job that was just marked complete — don't linger for a full planning day.

Fail-open behavior

The result cache is backed by Redis, and every Redis operation it performs fails open: if Redis is unreachable, misconfigured, or returns something unexpected, the affected call is logged and treated as a cache miss (or a no-op on writes) — never as an error surfaced to you. A broken cache degrades to "every request solves normally," not to an outage. This includes the case of a corrupted or non-JSON value ending up under a cache key: it's treated as a miss, not an exception.

You can disable the cache entirely, instantly, with RESULT_CACHE_ENABLED=false, with no other behavior change.

How this works for async requests

/optimize/async and /optimize/replan/async handle every incoming request as one of three cases:

1. Cache hit. A finished result already exists for this fingerprint. A new job is created already in its terminal completed state, with no solver subprocess ever launched. The very first GET /jobs/{job_id} call returns completed with a result — the response shape is identical to a genuinely-completed job, with no client-visible special case.
2. In-flight hit. An identical request is currently being solved under a different job_id. You get back the same job_id as the original request — no new job is created and no second solve is launched. Both callers poll the same job and observe the same eventual result. If that solve later fails, it is retried once in place (capped at a single retry) specifically because a duplicate caller is still waiting on the outcome; if the retry also fails, the job is left terminally failed and any later duplicate starts a fresh attempt of its own.
3. New request. Neither a cache hit nor an in-flight hit — the solve is launched normally, and the in-flight marker is written before the launch so that a concurrent duplicate arriving during the launch window can still attach to it.

In short: a duplicate in-flight async request attaches to the already-running job instead of starting a new solve. You never pay for the same solve twice.

Configuration

curl example

# First call: full solve time
time curl -s -X POST https://api.fieldgenius.be/api/v1/optimize/sync \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-adapter-key" \
  -H "X-Client-Key: your-client-key" \
  -d @request.json -o /dev/null
# real 0m30.3s

# Second call, identical body: served from cache, near-instant
time curl -s -X POST https://api.fieldgenius.be/api/v1/optimize/sync \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-adapter-key" \
  -H "X-Client-Key: your-client-key" \
  -d @request.json -o /dev/null
# real 0m0.3s

Python example (httpx)

import time
import httpx

BASE = "https://api.fieldgenius.be/api/v1"
HEADERS = {
    "X-API-Key": "your-adapter-key",
    "X-Client-Key": "your-client-key",
}

with httpx.Client(timeout=60, headers=HEADERS) as client:
    t0 = time.monotonic()
    first = client.post(f"{BASE}/optimize/sync", json=request_payload)
    first.raise_for_status()
    print("first call:", time.monotonic() - t0, "seconds")

    t0 = time.monotonic()
    second = client.post(f"{BASE}/optimize/sync", json=request_payload)
    second.raise_for_status()
    print("second call (cached):", time.monotonic() - t0, "seconds")