Configuration

Configure — the front door

Call Configure once at process start. It stores the api key and the optional Attributes transform as a package global, and kicks off a background fetch so a later NewClient(user).GetFlag() resolves against real rules without any explicit init.

shipeasy.Configure(shipeasy.Options{
    APIKey: os.Getenv("SHIPEASY_SERVER_KEY"),
    Attributes: func(u any) shipeasy.User {
        acct := u.(*Account)
        return shipeasy.User{"user_id": acct.ID, "plan": acct.Plan}
    },
})

Configure is first-config-wins (idempotent): the first call registers the configuration and starts the fetch; subsequent calls are no-ops. After it runs, build a cheap user-bound Client per request with NewClient(user).

For the full Options field table see Installation.

The Attributes transform & identity default

Attributes func(any) shipeasy.User maps your user value (any shape) to the Shipeasy attribute map used for every evaluation. It is applied once in NewClient(user) and the result is cached on the bound Client.

If you omit it, the identity transform is used: a shipeasy.User (or a map[string]any) passed to NewClient is used as-is; nil becomes an empty map; any other type degrades to an empty map (unidentified user) with a warning.

init / poll vs one-shot

You never start the fetch yourself — Configure owns the fetch lifecycle, and two Options fields choose its shape:

• default — Configure does a one-shot fire-and-forget fetch in the background, then never refreshes. Ideal for short-lived / serverless processes.
• Poll: true — Configure does an initial fetch plus a periodic background refresh (default interval 30s, re-tuned from the edge's X-Poll-Interval header), so flags stay fresh without a redeploy. Use this for long-running servers.
• NoInitialFetch: true — suppresses even the one-shot fetch (the init=false escape hatch). Ignored when Poll is true.

// Long-running server that wants live updates:
shipeasy.Configure(shipeasy.Options{
    APIKey: os.Getenv("SHIPEASY_SERVER_KEY"),
    Poll:   true,
})

Change listeners — OnChange

When polling is on (Poll: true), register a callback fired after a background poll loads new data (a 200, not a 304). It returns a cancel func:

cancel := shipeasy.OnChange(func() {
    log.Println("flags/experiments changed; re-render or warm caches")
})
defer cancel()

OnChange requires Configure(Options{Poll: true}) — no poll runs otherwise, so the listener never fires. A panicking listener is recovered and logged so it can't take down the poll loop.

Env-var convention

The SDK authenticates with your project's server key. Read it from the environment — never hard-code it:

export SHIPEASY_SERVER_KEY="sk_server_..."