Queue parity: (app_id, request_id) signatures, cancel, webhooks

[mculp]

Second PR in the parity stack (stacked on #3). Brings the queue API in line with the official fal clients (JS / Python / PHP).

Review #3 first — this branch targets chore/foundation, so the diff here is only the queue work.

What changed

• EndpointId — a value object that parses fal-ai/flux/schnell into the run path (full id) and the queue application path (fal-ai/flux). Namespaced ids (workflows/, comfy/) keep three segments. This is the one place that knows the parsing rule.
• Endpoints rebuilt around it — Run/Submit address the full id; Status/Result/Cancel are built from the app root, so nested ids resolve to the correct /{app}/requests/{id}/... path. Submit appends ?fal_webhook= when given a URL.
• Queue#status / #result now take (app_id, request_id) instead of a raw URL — matching the other clients and the README. ⚠️ Breaking, but pre-1.0 and the previous form was undocumented.
• Queue#cancel(app_id, request_id) — true once cancellation is requested, false on HTTP 400 (already finishing), raises otherwise.
• logs: on subscribe/status; webhook_url: on subscribe/submit.
• SubmitResponse gains app_id and cancel_url.
• Connection#put added; post/get/put collapsed onto one verb-dispatching path.

Why the integration tests are a correctness proof

The queue is per-app: fal-ai/flux/schnell submits under the full path but is polled under fal-ai/flux. The existing nested-model integration tests stub the server's app-rooted URLs end to end, so a green suite means EndpointId constructs exactly the URLs the gateway returns — the same behaviour the prior "trust the returned URL" code had, now with the ergonomic (app_id, request_id) API.

Verification

• 158 examples, 0 failures on Ruby 3.4.2 and 4.0.0 (up from 136).
• RuboCop: 34 files inspected, no offenses detected.

🤖 Generated with Claude Code

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ee34e708-11d3-44a3-b479-c4a9e67da296

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/queue-parity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR brings the Ruby fal client's queue API to parity with the official JS/Python/PHP clients by introducing EndpointId — a value object that encapsulates the owner/alias vs. owner/alias/variant split — and rebuilding the queue endpoints around it.

• EndpointId centralises the rule that fal-ai/flux/schnell submits on the full path but is polled under fal-ai/flux, eliminating all manual string splitting elsewhere; namespaced ids (comfy/, workflows/) are handled as a special case keeping three segments.
• Queue#status/#result signatures changed from a raw URL to (app_id, request_id), and a new Queue#cancel method is added (PUT, returns true/false/raises); Connection gains a #put verb alongside a refactored single-dispatch perform private method.
• SubmitResponse is extended with app_id and cancel_url; subscribe and status gain logs: and submit/subscribe gain webhook_url: keyword options.

Confidence Score: 5/5

Safe to merge — the changes are well-scoped, the URL construction logic is correct end-to-end as proven by the WebMock integration tests, and no data-loss or correctness regressions were found.

The EndpointId parsing logic, the per-verb Connection dispatch, and the cancel true/false/raise semantics are all exercised by the test suite at both the unit and integration level. The breaking API changes are documented in the CHANGELOG and are pre-1.0. No issues were found in the changed code beyond the points already raised in previous review threads.

spec/fal/integration_spec.rb — the multi-step polling integration test was removed (flagged in a prior thread); everything else is straightforward.

Important Files Changed

Filename	Overview
lib/fal/endpoint_id.rb	New value object cleanly encapsulates the submit-path vs. app-path distinction; NAMESPACES constant handles comfy/workflows correctly; coerce, equality, and hash are all implemented.
lib/fal/endpoints.rb	QueueRequest base class + Status/Result/Cancel subclasses replace the old Url wrapper; CGI.escape used correctly for webhook URL encoding; Status's keyword-forwarding initializer is valid Ruby 3+.
lib/fal/queue.rb	Public API migrated to (app_id, request_id) signatures; cancel correctly maps HTTP 400 → false and re-raises anything else; require_request_id guards the only truly required field.
lib/fal/connection.rb	post/get/put now share a single perform+handle_response path; body_options correctly omits the body keyword when nil, avoiding spurious empty-body PUT/GET calls.
lib/fal/subscriber.rb	Updated to use (app_id, request_id) from SubmitResponse; logs: keyword threaded through correctly.
spec/fal/endpoint_id_spec.rb	New spec covers to_s, app derivation (no variant, one variant, deeply nested, comfy namespace, workflows+variant), coerce, and value equality.
spec/fal/integration_spec.rb	cancel and webhook tests added; subscribe multi-step polling test removed (replaced by single-COMPLETED stub); response_url assertion dropped from submit test.
spec/fal/queue_spec.rb	All queue methods updated to new signatures; cancel covered for success, 400, and other errors; webhook and missing-request-id paths tested.
spec/fal/endpoints_spec.rb	All endpoint classes covered including webhook URL encoding and logs query parameter; reorganised as nested describes.

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant Q as Queue
    participant EI as EndpointId
    participant Conn as Connection
    participant API as fal API

    Note over C,API: submit
    C->>Q: submit("fal-ai/flux/schnell", input, webhook_url:)
    Q->>EI: coerce("fal-ai/flux/schnell")
    Q->>Conn: post(Submit endpoint, body: input)
    Note right of Conn: POST queue.fal.run/fal-ai/flux/schnell[?fal_webhook=...]
    Conn->>API: HTTP POST
    API-->>Conn: "{request_id, status_url, cancel_url, ...}"
    Conn-->>Q: Response
    Q-->>C: SubmitResponse(app_id, request_id, ...)

    Note over C,API: Subscriber polling loop
    loop until completed or timeout
        C->>Q: status("fal-ai/flux/schnell", request_id, logs:)
        Q->>EI: coerce → .app → "fal-ai/flux"
        Q->>Conn: get(Status endpoint)
        Note right of Conn: GET queue.fal.run/fal-ai/flux/requests/{id}/status[?logs=1]
        Conn->>API: HTTP GET
        API-->>Conn: "{status: IN_QUEUE|IN_PROGRESS|COMPLETED}"
        Conn-->>Q: Response
        Q-->>C: Status object (yield to block)
    end

    C->>Q: result("fal-ai/flux/schnell", request_id)
    Q->>EI: coerce → .app → "fal-ai/flux"
    Q->>Conn: get(Result endpoint)
    Note right of Conn: GET queue.fal.run/fal-ai/flux/requests/{id}
    Conn->>API: HTTP GET
    API-->>C: result data

    Note over C,API: cancel (optional)
    C->>Q: cancel("fal-ai/flux/schnell", request_id)
    Q->>EI: coerce → .app → "fal-ai/flux"
    Q->>Conn: put(Cancel endpoint)
    Note right of Conn: PUT queue.fal.run/fal-ai/flux/requests/{id}/cancel
    Conn->>API: HTTP PUT
    alt 2xx
        API-->>C: true
    else HTTP 400
        API-->>C: false
    else other error
        API-->>C: raises ApiError
    end

Loading

_{Reviews (2): Last reviewed commit: "Guard require_request_id with an explici..." | Re-trigger Greptile}

[mculp]

Consolidating the remaining stack into #5 (now targeting main).

After #3 merged, this PR can no longer stand alone correctly:

• It still uses http.rb, whose llhttp-ffi native build fails on Ruby 4.0 now that main no longer commits Gemfile.lock — the Faraday switch that fixes it lives in Model API client parity: queue + streaming + uploads + webhooks on Faraday (v0.3.0) #5.
• Its EndpointId#app truncation 404s nested model ids; the full-id correctness fix lives in Model API client parity: queue + streaming + uploads + webhooks on Faraday (v0.3.0) #5.

So the queue-parity work + its required fixes ship together in #5 as one clean, CI-green PR with the final code (no transient broken state on main). All three review threads here are addressed in #5. Branches are intact, so happy to re-split if you prefer separate reviews.