Idiomatic F# handler discovery: module-level functions, discriminated unions, and records

[jeremydmiller]

Context

Today's convention-based handler discovery (Wolverine/Configuration/HandlerDiscovery.cs) looks for instance methods named Handle / Consume / Orchestrate / Start / etc. on classes. That maps cleanly to C# idioms (a class + a Handle(...) method), but it's awkward for F# users, who prefer module-level functions, discriminated unions for commands, and records colocated with their handlers.

Wolverine.Http already handles F# reasonably via attribute-driven routing — [<WolverinePost("/foo")>] let myHandler() = ... in src/Http/WolverineWebApiFSharp/Library.fs works today. The gap is on the non-HTTP convention-based discovery side: messaging / mediator handlers in idiomatic F#.

Goal

Treat three idiomatic F# shapes as first-class for handler discovery, alongside today's class-with-Handle-method shape.

The three shapes

1. Module-level handler functions

The most common F# idiom:

module CreateOrder

open Wolverine

let handle (cmd: CreateOrderCommand) (repo: IOrderRepository) =
    // ...

A F# module compiles to a [CompilerGenerated] sealed abstract class (i.e. a static class) with static methods. HandlerDiscovery._validMethods already includes the right method names — the work is teaching the discovery layer to find them as static methods on static classes (today the method-match path is instance-method-oriented).

Curried dependency parameters should bind via the existing IoC-resolution path (each curried parameter is just another argument in the compiled signature).

2. Discriminated unions as command messages

type OrderCommand =
    | Create of CreateOrderCommand
    | Cancel of CancelOrderCommand
    | Ship of ShipOrderCommand

F# DUs compile to a base class + nested case classes. Two routing models worth considering, settled in the spike:

• (a) Treat the DU root as one message type. Caller sends OrderCommand, handler does internal match. Lowest-friction, but every case shares a single handler chain and routing rule.
• (b) Discover each case as its own routable message type and let multiple handlers (or one handler that pattern-matches by case) be invoked. Closer to the F# idiom of "each case is a logical command."

(a) very likely works already if Wolverine can resolve the DU root as a concrete message type. (b) is the interesting one and the real ask.

3. Records as commands with colocated handlers

type CreateOrderCommand = {
    Id: string
    Quantity: int
} with
    static member handle (cmd: CreateOrderCommand) (repo: IOrderRepository) =
        // ...

F# folks often colocate the command and its handler on the same type via static member. Discovery should find static member handle on the record type so this organization style works without an external module.

Out of scope (for this issue)

The bigger F# story — teaching every Wolverine Frame subclass to emit F# adapter code — is intentionally deferred to a separate follow-up issue. #384 (already merged) shipped the F# emitter infrastructure at the JasperFx layer; the Wolverine-side frame audit + per-surface F# test projects + dedicated F# CI workflow will be planned in that follow-up. This issue is only about discovery.

Existing F# footprint to consider

• src/Http/WolverineWebApiFSharp/ — proves attribute-driven F# HTTP discovery works. Worth reading for shape-of-the-thing reference; the messaging convention-discovery work in this issue should compose with it cleanly (an F# project mixing [<WolverinePost>] HTTP endpoints with module-level message handlers should Just Work).

Open design questions (settle during the spike)

1. DU dispatch model — (a) DU-as-one-message, (b) per-case-as-message, or both with an attribute toggle? See §"Discriminated unions" above. Likely (a) ships as a free side-effect and (b) is the interesting design fork.
2. task / Task / Async returns. F# handlers commonly return task { ... } (Task / Task<'T>) but Wolverine should also accept idiomatic Async<'T> returns and bridge to the task-based execution path. Worth deciding whether Async<'T> is supported in v1 or deferred.
3. F# unit return ≡ C# void. Confirm the return-type inspection treats Microsoft.FSharp.Core.Unit as "no cascaded message," same as void/Task.
4. Curried vs. tupled signatures. Curried let handle msg dep1 dep2 = ... compiles to a method with N parameters; tupled let handle (msg, dep1, dep2) = ... compiles to a single tuple parameter. The first composes with Wolverine's argument injection; the second probably doesn't and should be explicitly rejected with a clear error.
5. Discovery target list. Today's HandlerDiscovery scans assemblies for concrete message types + their handlers. Module-class scanning may need a separate include rule (the _messageQuery.Excludes.IsStatic() line excludes static classes as messages; the handler-method side likely needs the inverse hint for methods).

Acceptance criteria

• A module-level let handle (msg: Foo) (deps...) = ... in an F# project is discovered as a handler for Foo without any extra attributes.
• A static member handle (msg: Foo) (deps...) = ... on an F# record type is discovered the same way.
• DU-as-one-message routing works (the DU root type is a routable message; handler dispatches via match).
• Per-DU-case routing model decided + implemented (or explicitly deferred with rationale).
• Curried dependencies inject via the standard IoC path; tupled let handle (msg, dep) = ... either works or fails with a clear "use curried form" error.
• task { ... } returning Task / Task<'T> from an F# handler works for both fire-and-forget and InvokeAsync<T>.
• Microsoft.FSharp.Core.Unit return treated as void (no cascade).
• A small F# test project under the existing src/Http/WolverineWebApiFSharp/ (or a new sibling) exercises each shape end-to-end through an in-process host.
• Brief documentation under /guide/handlers/ (or similar) showing each F# shape with a working snippet.

Scope keepers

• Stay in Wolverine. If anything turns out to be general enough to belong at the JasperFx layer (e.g. F# type-inspection helpers), lift it later in a separate change.
• No carry-forward from Support Inline sender & receiver with AWS SQS #383 / Allow for SQS mapping for interop #384 — those address the codegen emitter layer; this issue is purely about discovery on the C#-runtime side.

Related

• Sibling: F# code generation audit: teach every Frame subclass to emit F# (phased) #2969 — F# code-generation audit (teach every Wolverine Frame subclass to emit F# code, phased, with per-surface F# test projects in a separate solution and a dedicated CI workflow).
• Support Inline sender & receiver with AWS SQS #383 / Allow for SQS mapping for interop #384 — context only; F# emitter infrastructure that the future codegen follow-up will consume.

[jeremydmiller]

Moving this to a discussion just to cheat and get to inbox 0