Context Handling in fp-go

fp-go Context Handling

Core Principle

In imperative Go the context is threaded by hand: every function takes ctx first, values are read with ctx.Value(k).(T), scopes are opened with ctx, cancel := context.WithTimeout(...); defer cancel().

In fp-go the context is the Reader environment. A computation is a description func(context.Context) … that runs only when a context is supplied. Therefore:

1. Pipelines never mention ctx. Build them from operators; the context flows implicitly.
2. Supply the context exactly once, at the edge — HTTP handler (r.Context()), main, or a test (t.Context()).
3. Read the context with operators (Ask, FromReader, AskValue), never with ctx.Value(k).(T).
4. Scope the context with operators (WithValue, WithTimeout, WithDeadline, Local), never with context.With* + defer cancel().
5. Only request-scoped data goes into the context. Dependencies (DB, clients, config) belong in Effect[Deps, A].

Before You Generate

fp-go is low-frequency in training data, so signatures are easy to misremember. For any combinator not shown below, look it up via the fp-go MCP server's search_examples / get_example tools (see the fp-go-mcp skill) instead of guessing. After writing code, run go build ./... and go vet ./... and fix any type-parameter or argument-order errors before presenting it.

Packages and Availability

Local's argument is func(ctx) Pair[context.CancelFunc, context.Context] in the standard packages and func(ctx) (context.Context, context.CancelFunc) in IRR.

1. Running at the Edge

// HTTP handler: the request context is supplied once
func handler(w http.ResponseWriter, r *http.Request) {
    res := handleRequest(r)(r.Context())()   // Result[Response] — ONE value
    resp, err := R.Unwrap(res)               // bridge back to (A, error)
    // ...
}

// Tests: use t.Context(), cancelled automatically when the test ends
res := pipeline(t.Context())()

Never capture a ctx in a closure and never store it in a struct; pass it only when running.

2. Bridging func(ctx, …) (T, error)

Existing context-first Go functions are lifted, not wrapped by hand:

// func(context.Context, string) ([]byte, error)  ->  func(string) RIO.ReaderIOResult[[]byte]
fetch := RIO.Eitherize1(fetchBytes)

// idiomatic package: the shape is already native
fetchI := IRR.From1(fetchBytes)                       // func(string) IRR.ReaderResult[[]byte]

// and back, for APIs that expect the Go shape
fetchGo := RIO.Uneitherize1(fetch)                    // func(context.Context, string) ([]byte, error)

The lifted function receives the pipeline's (possibly scoped) context — timeouts and values applied with the operators below reach it automatically.

3. Reading the Context

AskValue never panics and never fails: Some(v) if the key holds a V, None if it is absent or holds another type. The caller decides what "missing" means.

Keys and Accessors

Use an unexported key type — never plain strings or exported types — and keep one read and one write accessor next to each key, so the rest of the code never touches the key:

type ctxKey int

const (
    userKey ctxKey = iota
    requestIDKey
)

var errNoUser = errors.New("no authenticated user in context")

// optional value: None -> default
func requestID() RIO.ReaderIOResult[string] {
    return F.Pipe1(
        RIO.AskValue[string](requestIDKey),
        RIO.Map(O.GetOrElse(LZ.Of("-"))),
    )
}

// required value: None -> error
func requireUser() RIO.ReaderIOResult[User] {
    return F.Pipe1(
        RIO.AskValue[User](userKey),
        RIO.Chain(RIO.FromOption[User](F.Constant(errNoUser))),
    )
}

// writer: scopes the value to the wrapped computation
func withUser[A any](u User) RIO.Operator[A, A] {
    return RIO.WithValue[A](userKey, u)
}

RR and IRR have no FromOption, so the required-value accessor looks slightly different there:

// RR: lift result.FromOption (Option[User] -> Result[User]) into the reader
func requireUserRR() RR.ReaderResult[User] {
    return F.Pipe1(
        RR.AskValue[User](userKey),
        RR.ChainEitherK(R.FromOption[User](LZ.Of(errNoUser))),
    )
}

// IRR: ChainOptionK expects an idiomatic (B, bool) Kleisli; O.Unwrap turns the Option into that tuple
func requireUserIRR() IRR.ReaderResult[User] {
    return F.Pipe1(
        IRR.AskValue[User](userKey),
        IRR.ChainOptionK[O.Option[User], User](LZ.Of(errNoUser))(O.Unwrap[User]),
    )
}

The IRR form needs the explicit [O.Option[User], User] because ChainOptionK receives only the onNone error first, so Go cannot infer A and B from it.

4. Scoping the Context

Scoping operators run the wrapped computation with a derived context. The caller's context is never modified, and the derived context's cancel function is always released when the computation completes — no defer cancel(), no leaks.

They are ordinary operators and compose in Pipe. The context flows from the last operator inwards, so the last one is applied first:

func handleRequest(r *http.Request) RIO.ReaderIOResult[Response] {
    return F.Pipe4(
        requireUser(),
        RIO.Chain(loadProfile),
        RIO.WithTimeout[Response](5*time.Second),               // bounds the work above
        withUser[Response](userFromRequest(r)),                  // visible to everything above
        RIO.WithValue[Response](requestIDKey, r.Header.Get(HD.XRequestID)),
    )
}

Scope as narrowly as the requirement: put WithTimeout directly after the step it should bound, not around the whole handler, if only one call needs it.

Deriving the Context from an Effect

When the new context value itself needs IO (generating an ID, loading a token), use LocalIOK / LocalIOResultK with the context/reader building blocks:

// uuid.NewString is a func() string, i.e. already an IO[string]
func addRequestID(ctx context.Context) IO.IO[RIO.ContextCancel] {
    return F.Pipe1(
        uuid.NewString,
        IO.Map(F.Flow3(
            CR.WithValue[string](requestIDKey), // string -> Endomorphism[context.Context]
            RD.Read[context.Context](ctx),      // apply it to ctx
            CR.NopCancel,                       // -> Pair[CancelFunc, context.Context]
        )),
    )
}

scoped := RIO.LocalIOK[Response](addRequestID)(handler)

LocalIOResultK does the same with a fallible derivation; on failure the wrapped computation does not run.

5. Cancellation

• In RIO, RR and IRR, Chain checks the context before each step: once the context is cancelled, the next step does not run and the result is Left(context.Cause(ctx)). Map does not check (pure functions are cheap).
• RIOC (context/readerio) has no error channel, so it cannot short-circuit; use it only for IO that is fine to complete.
• WithContext(ma) / WithContextK(f) add the same check explicitly, e.g. before an expensive first step.
• Delay, retries, Bracket / WithResource and the HTTP client observe cancellation.
• Leaf computations that block (loops, select, custom IO) must watch ctx.Done() themselves and return ctx.Err() / context.Cause(ctx):

func waitForJob(id string) RIO.ReaderIOResult[Job] {
    return func(ctx context.Context) RIO.IOResult[Job] {
        return func() R.Result[Job] {
            select {
            case job := <-jobs(id):
                return R.Of(job)
            case <-ctx.Done():
                return R.Left[Job](context.Cause(ctx))
            }
        }
    }
}