Clarify Flow Routing Design

[theakashsarkar]

Flow Routing Design Clarification

I’d like to better understand the intended design for flow routing before starting an implementation.

I noticed that FlowResolver and FlowResolution are already defined in the gateway module:

public interface FlowResolver {

    Optional<FlowResolution> resolve(
        GatewayRuntimeEntry gateway,
        GatewayRequestContext requestContext
    );
}

and:

public record FlowResolution(String flowKey) {}

However, I’m not yet clear on how a request is expected to be mapped to a Flow.

Could you clarify the intended behavior for the following?

• What exactly does a Flow represent in Funchole?

• How should a request be resolved to a Flow?

  • Gateway hostname?
  • Request path?
  • HTTP method?
  • A combination of these?

• Where should the flowKey come from?

• Is the Flow-to-route mapping expected to be stored in PostgreSQL?

• Is a Flow associated with a single Gateway, or can the same Flow be exposed through multiple Gateways?

• Should routing initially support exact paths only, or should path parameters/prefix matching be considered?

I’d like to understand the intended architecture before implementing anything so that the contribution follows the project's design direction.

[hashemirafsan]

Thanks for raising this. The intended routing model is:

Request → Gateway (hostname) → Flow (HTTP method + path) → Invocation

A Flow is an executable workflow and should have its own stable flowKey. The flowKey should not be derived from the URL.

For example:

• GET /orders → flw_orders_list
• POST /orders → flw_orders_create
• GET /orders/123 → flw_order_details

The relationship should be:

Gateway → FlowRoute → Flow

This allows the same Flow to be exposed through different gateways or routes later.

Flow and route definitions will be managed by the Controlplane and persisted in PostgreSQL. The Gateway should not query PostgreSQL for every request; routing data should be synchronized into an in-memory runtime representation.

For the first implementation, I suggest keeping FlowResolver simple:

gateway + HTTP method + exact path → flowKey

Parameterized routes, wildcards, and priority rules can be added incrementally afterward.

[hashemirafsan]

I have something in my mind for flow control and further development.

The intended Controlplane model is:

Flow Definition → Validation → Version → Adoption → Gateway Runtime Sync

A Flow should be treated as a versioned executable definition, not only as a route target.

For example, a Flow may contain:

• Functions
• Sub-Flows
• Execution order / transitions
• Input/output mapping
• Runtime metadata

Conceptually:

Flow → Step → Function | Sub-Flow

A Sub-Flow should reference another Flow by its stable flowKey and a specific version/reference rather than duplicating its definition.

Example:

checkout-flow
→ validate-cart
→ payment-flow (sub-flow)
→ create-order
→ notification

Controlplane adoption

The Controlplane should initially support this lifecycle:

1. Create a Flow with a stable flowKey.
2. Add/update Flow steps.
3. Allow a step to reference either a Function or another Flow.
4. Validate the complete Flow graph before adoption.
5. Reject invalid references and circular Flow dependencies.
6. Create an immutable Flow version.
7. Mark a version as adopted / active.
8. Attach FlowRoute entries to the adopted Flow.
9. Publish the adopted runtime definition to the Gateway/runtime layer.

The Gateway should only receive the runtime-ready representation. It should not resolve Flow composition from PostgreSQL during a request.

So the separation becomes:

Controlplane
Flow authoring → validation → versioning → adoption

Gateway
Gateway + Method + Path → flowKey/version

Invocation
Execute Flow → Function/Sub-Flow → Result

For the first implementation, I suggest keeping Flow composition simple:

• sequential steps
• Function step
• Sub-Flow step
• immutable adopted version
• circular dependency validation

Branching, conditions, retries, parallel steps, rollback, etc. can be introduced incrementally afterward.

[hashemirafsan]

I've added flow related migration

let me know if any improvement needed