When to cache
Problem: You need data from one resource type when processing another, such as resolving user IDs to emails when you emit grants.
When not to cache:
- Across syncs. In daemon mode, the same connector process runs many syncs.
- Large datasets that don’t fit in memory.
- Data that changes frequently during a sync.
What the SDK guarantees
A cache is only useful if you know when it’s filled. These facts decide how you design one:- In a full sync, every
Listcall finishes before anyGrantscall. Registration order doesn’t matter. - That isn’t true everywhere. A targeted sync fetches specific resources without listing the rest. A sync can also resume from a checkpoint in a new process, where nothing from the earlier run is in memory.
Grantsmust work when the cache is empty. - Builders can run concurrently. With
--workers N(N greater than 0), the SDK syncs in parallel. The default is sequential. - The connector lives as long as the process. The SDK builds your connector once, and in daemon mode the same instance serves every sync.
Use the session store
Problem: Share data betweenList() and Grants() without managing a cache yourself.
Solution: V2 syncers receive a session store in opts.Session. The SDK clears it at the end of each sync, so nothing leaks into the next one.
First enable the store when you run the connector:
List and read from it in Grants:
session is github.com/conductorone/baton-sdk/pkg/session.
Why: The session store survives a resume and is scoped to one sync. It has limits you should plan for:
- Treat it as a remote service, not a map. Batch your reads and writes with the
Manyhelpers, and tolerate misses. - Calls have a size limit of about 4 MB. Cache IDs and small records, not whole API responses.
- It’s available only to V2 syncers, and only when you enable it. Without it, calls return
session.ErrSessionStoreDisabled.
Cache in memory
Problem: Cache data in the connector itself, for a connector that doesn’t use the session store. Solution: Keep the cache on the connector struct, guard it, and key it by the sync ID so each sync starts empty:c.cacheFor(opts.SyncID) and treat a missing entry as a miss, not an error:
sync.Map is safe when builders run concurrently. Keying by SyncID means a new sync never sees data from the previous one. Falling back to the API on a miss keeps targeted syncs and resumed syncs correct.
Cross-resource lookups
Problem: When you emit grants, you have member IDs but need to know whether each is a user or a group. Solution: Record each ID’s type while you list, and look it up when you emit grants:List avoids a lookup for each member during Grants. Because the cache can be empty in a targeted or resumed sync, choose a default that’s safe, or look the ID up in the API.
Package-level caches
- Sync 1 runs and caches users A, B, and C.
- User B is deleted from the target system.
- Sync 2 runs in the same daemon process.
- The cache still contains user B.
- Grants for user B look valid but point at a deleted user.
- Access reviews show access that doesn’t exist.
Built-in HTTP cache
Theuhttp package caches successful GET responses in memory. It keeps them for one hour by default, within a 5 MB limit. The SDK clears these caches at the end of every sync.
Problem: A cached response is stale, or you’re testing and want every request to reach the API.
Solution: Opt out for one request, or turn the cache off for the whole process:
BATON_HTTP_CACHE_TTL (seconds) and BATON_HTTP_CACHE_MAX_SIZE (megabytes).