Skip to main content
Each recipe includes the problem, solution code, and rationale.

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 List call finishes before any Grants call. 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. Grants must 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 between List() 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:
Then write to it in 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 Many helpers, 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:
Builders call c.cacheFor(opts.SyncID) and treat a missing entry as a miss, not an error:
Why: 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:
Why: Many APIs return member IDs without a type. Recording the type during 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

Avoid package-level caches. A package-level sync.Map persists for the life of the process, so in daemon mode it carries data from one sync into the next.
What goes wrong:
  1. Sync 1 runs and caches users A, B, and C.
  2. User B is deleted from the target system.
  3. Sync 2 runs in the same daemon process.
  4. The cache still contains user B.
  5. Grants for user B look valid but point at a deleted user.
  6. Access reviews show access that doesn’t exist.
A cache on the connector struct has the same problem, because the SDK builds the connector once per process. A struct field isn’t fresh per sync. Use the session store, or key the cache by sync ID as shown above. To check your connector for package-level caches:

Built-in HTTP cache

The uhttp 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:
You can also tune the cache with BATON_HTTP_CACHE_TTL (seconds) and BATON_HTTP_CACHE_MAX_SIZE (megabytes).

Memory-bounded caching

Problem: Caching all users exhausts memory in a large organization. Solution: For large datasets, use a bounded cache, or skip caching:
Alternative: Batch your lookups instead of caching everything:
Why: Memory is finite. A connector that runs out of memory is worse than one that makes extra API calls.