Observe cache eligibility¶

Run the compact FastAPI self-check to see these outcomes against a disposable replica set. The fragments below come from that executable program: owned contains its application resources, and observed_bypass checks public snapshots before and after a fully consumed read.

Miss followed by hit¶

With the stream healthy and the document not yet cached, the first request records one miss and the repeated request records one hit. Startup and concurrent writes can affect admission; the self-check seeds data before application startup and waits for stream readiness.

    before = owned.manager.snapshot()
    first = http.get("/products/book")
    missed = owned.manager.snapshot()
    second = http.get("/products/book")
    hit = owned.manager.snapshot()
    require(
        condition=first.status_code == second.status_code == 200
        and first.json() == second.json(),
        message="repeated endpoint reads disagree",
    )
    require(
        condition=missed.misses - before.misses == 1 and hit.hits - missed.hits == 1,
        message="missing endpoint miss followed by hit",
    )
    print("repeated endpoint: misses +1, then hits +1")

Deliberate bypasses¶

Each operation below delivers a document but records one ordinary bypass and one matching reason, with no hit or miss. Returning a result alone is not evidence it was cached.

    async with owned.client.start_session() as session:
        read = partial(owned.cached.find_one, {"_id": "book"}, session=session)
        await observed_bypass(owned, BypassReason.SESSION, read)

    cursor = owned.cached.find({"_id": "book"}, allow_partial_results=True)
    await observed_bypass(owned, BypassReason.UNSUPPORTED_OPTIONS, cursor.to_list)

    pipeline: list[dict[NonEmptyStr, object]] = [
        {"$match": {"_id": "book"}},
        {"$sample": {"size": 1}},
    ]
    return await (await owned.cached.aggregate(pipeline)).to_list()

The sampling pipeline is executed inside the self-check's observation wrapper so the snapshot difference covers both aggregate() and cursor consumption. It selects the seeded book before sampling, making delivery predictable while the pipeline remains ineligible for caching.

Oversized result¶

The example sets max_entry_bytes to 1 KiB and seeds a document with a 2,048-character description. Reading it delivers the complete document, records one miss and one oversized_bypasses event, and leaves ordinary bypasses unchanged. Repeating the read still cannot admit that document.

    before = owned.manager.snapshot()
    large = await owned.cached.find_one({"_id": "large"})
    after = owned.manager.snapshot()
    require(
        condition=large is not None and len(large["description"]) == 2048,
        message="oversized read did not deliver the complete document",
    )
    require(
        condition=after.oversized_bypasses - before.oversized_bypasses == 1
        and after.misses - before.misses == 1
        and after.bypasses == before.bypasses,
        message="oversized read did not record a miss and separate oversized bypass",
    )
    print("oversized: misses +1, oversized_bypasses +1, ordinary bypasses unchanged")

Direct reads¶

The PATCH response uses the raw collection and leaves hit, miss, and bypass counters unchanged. A direct read is not a cache bypass: it never enters the cached view. Session-bound reads through the cached view do enter it and record session bypasses.

These are selected examples. The API reference is the complete eligibility contract, and monitoring explains counter accounting and stream health. Snapshot differences are easiest to interpret in an isolated exercise; concurrent requests contribute to the same manager-wide counters.