FlowExtra.Client (flowextra v0.6.0)

Copy Markdown View Source

Abstraction to call the pipeline.

One budget (FX-006): call/3 and call!/3 start the clock at the public entry — queueing behind a busy client and the pipeline's execution share one absolute deadline, and the remaining budget is handed to the engine rather than a fresh default. Expected request failures (a missed deadline, a dead pipeline) raise as FlowExtra.PipelineError at the caller boundary without killing the reusable client; unexpected implementation failures crash it normally. Admission answers are expected request failures too (FX-001 closure): call/3 raises FlowExtra.AdmissionError the same way, and cast/2 reports the pipeline's own answer — :ok from the client means the pipeline accepted and accounted the work, a definite refusal arrives as {:error, :overloaded | :unavailable}, a lost admission endpoint arrives as {:error, :noprocess} (communication with the admission owner failed; whether the submission executed or produced effects before that failure is not established), and an outcome learned only by its acknowledgment timing out arrives as {:error, {:unacknowledged, ref}} — uncertain, never spelled as a refusal. See FlowExtra.Admission.submit/3 for what each shape lets the caller infer.

Summary

Functions

Calls the pipeline through the client GenServer. Expected request failures raise at this boundary; the client survives them.

One-shot call without a helper process (FX-006): direct delegation to the pipeline's call/3 with the caller's own remaining budget. Expected failures raise FlowExtra.PipelineError directly in the caller.

Casts through the client and returns the pipeline's own answer — :ok when the work was admitted and accounted; {:error, :overloaded | :unavailable} when the pipeline definitely refused it; {:error, :noprocess} when communication with the admission owner failed (the process was unavailable or terminated; whether the submission executed or produced effects before that failure is not established — not a definite refusal); and {:error, {:unacknowledged, ref}} when only the acknowledgment timed out (uncertain; the ref is the request identity).

Returns a specification to start this module under a supervisor.

Functions

call(pid, struct, timeout \\ 6000)

@spec call(GenServer.server(), struct(), timeout()) :: struct()

Calls the pipeline through the client GenServer. Expected request failures raise at this boundary; the client survives them.

call!(pipeline, struct, timeout \\ 6000)

@spec call!(FlowExtra.Pipeline.t(), struct(), timeout()) :: struct()

One-shot call without a helper process (FX-006): direct delegation to the pipeline's call/3 with the caller's own remaining budget. Expected failures raise FlowExtra.PipelineError directly in the caller.

cast(pid, struct)

@spec cast(GenServer.server(), struct()) ::
  :ok
  | {:error, :overloaded | :unavailable | :noprocess}
  | {:error, {:unacknowledged, reference()}}

Casts through the client and returns the pipeline's own answer — :ok when the work was admitted and accounted; {:error, :overloaded | :unavailable} when the pipeline definitely refused it; {:error, :noprocess} when communication with the admission owner failed (the process was unavailable or terminated; whether the submission executed or produced effects before that failure is not established — not a definite refusal); and {:error, {:unacknowledged, ref}} when only the acknowledgment timed out (uncertain; the ref is the request identity).

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start(pipeline, opts \\ [])

stop(pid)

@spec stop(GenServer.server()) :: :ok