Skip to content

feat(subscription): bill bound subscriptions only for their account, optional shared-pool fallback (HQ-Task T261106-02) - #11

Merged
AdoreJc merged 1 commit into
fork-mainfrom
hq/T261106-02-subscription-billing-fallback
Nov 6, 2026
Merged

AdoreJc merged 1 commit into
fork-mainfrom
hq/T261106-02-subscription-billing-fallback

Conversation

@AdoreJc

@AdoreJc AdoreJc commented Nov 6, 2026

Copy link
Copy Markdown
Owner

HQ-Task: T261106-02

Agent

  • Tool: Claude Code (desktop app, Code tab; session started by the HQ supervisor session)
  • Tool version: Claude Code desktop app (version not exposed to the session)
  • Model (full id): claude-opus-5-5
  • Host (CLI / IDE / GitHub coding agent / other): other (Claude desktop app, Windows 10)
  • Date (UTC): 2026-11-06

Note: the git user (AdoreJC) is not a historical core developer of this repository. The code in this PR was AI-generated under the user's instructions and is reviewed by the user's HQ supervisor process.

Links

User request

  • Verbatim (HQ task brief, user-confirmed plan):

订阅只为绑定账号买单,其他请求按原规则计费;账号限流时默认直接报错,套餐可开启回退。

  1. 定向请求只扣绑定的那个订阅:distributor 定向时把绑定的 UserSubscription.Id 和定向前的原分组写进 context。计费识别到后只从该订阅预扣……不看偏好、不回退钱包;不足时返回明确的订阅额度不足错误(ErrorCodeInsufficientUserQuota,带剩余和需要的额度)。
  2. 非定向请求不碰绑定订阅:PreConsumeUserSubscription 候选、HasActiveUserSubscription、UserActiveSubscriptionsAllowWalletOverflow 等跳过有生效绑定渠道的订阅……只有绑定订阅的用户,其他模型直接扣余额。
  3. 套餐新开关「账号限流时回退共享池并扣余额」:SubscriptionPlan 加字段……默认 false……购买/开订阅时快照到 UserSubscription(照 AllowWalletOverflow 做法,或说明为何不快照)。管理端套餐编辑抽屉加开关和说明,7 个 locale 同步,不改既有键的转义。
  4. 开关开启时:定向请求在绑定渠道遇到账号额度/限流错误……在重试循环里把分组切回原分组(原分组是 auto 时用 Auto 列表但排除专属组)继续选渠道;退回订阅预扣……改为钱包预扣,钱包不足返回钱包额度不足;只在尚未向客户端写出字节前回退;日志/消费记录能看出「绑定账号限流 → 回退共享池,扣余额」。
    开关关闭时(默认):不回退,返回明确错误,如「订阅账号的 5 小时额度已用尽,将于 HH:MM 重置」。重置时间优先取上游 -reset 响应头,其次取 channel.other_info.claude_passive_usage 采样;Codex 给通用限额提示。
  5. 不变:未绑定订阅的计费、钱包充值、Epay、订阅额度重置任务、PR fix(subscription): let bound users see and use their dedicated group (HQ-Task T261106-01) #10 的分组可见性逻辑。
  • Later constraints or corrections from the user (quote, or none): none

Out of scope — refuse

  • Matched: no (Claude Subscription (OAuth) / Codex channel binding exists only in this fork; this PR targets fork-main, not upstream)
  • If yes, what was told to the user (stop here; do not open a PR): n/a

Open gate — do not open unless all are satisfied

  • Out of scope (including pass-through-only forwarding): no
  • Usage / configuration / integration (answered instead of opening): no
  • Required issue facts present without invention: yes (from the HQ brief; current behavior read from code on fork-main 5bd57e8)
  • Verification is actual commands or steps and observed results, not only go build or tests passed: yes
  • Body is short and factual; no unfiltered AI-generated text: yes
  • Open: yes
  • If no, what was told to the user (stop here): n/a

Kind

  • Bug fix
  • New feature
  • Performance / refactor
  • Docs
  • Other:

Issue facts

  • Actual behavior (fork-main 5bd57e8): billing ignores routing. PreConsumeUserSubscription takes any active subscription (end_time asc), so every request of a bound user, including other models on default/Auto, is charged to the bound subscription first, with wallet overflow by default; a user preference wallet_first/wallet_only makes even bound-account requests pay from the wallet. Retries of a steered request select from relayInfo.TokenGroup (the token group, not the dedicated group), so after a bound-account error the retry could land in the shared pool while the subscription pays.
  • Impact: subscribers pay their subscription for shared-pool traffic; the bound account's usage limit surfaces as a raw upstream 429.
  • Frequency: every request of a user with a bound subscription.
  • Evidence that the problem is in new-api: code paths above; the Docker walkthrough shows the new behavior against a mock upstream.
  • Applicable types and their fields: billing (pre-consume source selection, refund, consume log other), relay (retry group, limit detection), frontend (plan drawer switch), database (one new plan column).

Change

Billing attribution (service/billing_session.go, service/funding_source.go, model/subscription.go)

Request Subscription kind Preference Billed to
steered to the binding (model served by the bound channel) bound subscription any (subscription_first / subscription_only / wallet_first / wallet_only) that bound subscription only; short → 403 insufficient_user_quota "绑定账号的订阅额度不足:剩余 X,需要 Y"; never the wallet, never another subscription
steered, then fell back (switch on, account limited) — any wallet only (insufficient → wallet error)
not steered ordinary (unbound) subscriptions unchanged unchanged rules, bound subscriptions excluded from candidates, existence check and allow_wallet_overflow decision
not steered only bound subscriptions subscription_first / wallet_* wallet (no unbound subscription exists)
not steered only bound subscriptions subscription_only "no active subscription" error, as for a user without subscriptions
  • middleware/distributor.go records relaycommon.SubscriptionRoute{SubscriptionId, ChannelId, Group, OriginalGroup} on every steered request (also when the token already uses the dedicated group); GenRelayInfo copies it to RelayInfo.SubscriptionRoute. model.ResolveSubscriptionRouteGroup became ResolveSubscriptionRoute (returns the binding).
  • New model.PreConsumeBoundUserSubscription(requestId, userId, subscriptionId, amount); it and PreConsumeUserSubscription share one transaction body (idempotent request record, row lock, maybeResetUserSubscriptionWithPlanTx). Unbound = COALESCE(bound_channel_id, 0) = 0. Renamed HasActiveUnboundUserSubscription, UserActiveUnboundSubscriptionsAllowWalletOverflow (single callers).
  • service.RelayRetryGroup: retries of a steered request stay in the dedicated group (normal relay and async task loops).

Limit detection and fallback (service/subscription_route.go, controller/relay.go)

  • Trigger, only on an attempt that ran on the bound channel: HTTP 429, error type rate_limit_error / usage_limit_reached / rate_limit_exceeded, anthropic-ratelimit-unified-status: rejected, or any anthropic-ratelimit-unified-{5h,7d,7d_oi}-status: rejected / utilization ≥ 1. The Claude OAuth and Codex adaptors keep the answer's anthropic-ratelimit-unified-* / x-codex-* / retry-after headers on the request for this check.
  • Switch off (default) or fallback impossible (response content already sent, or the token itself uses the dedicated group): 429 subscription_account_limited, skip-retry, e.g. 订阅账号的 5 小时额度已用尽,将于 2026-11-06 16:25 EST 重置. Window/reset: the window with the latest reset among rejected ones from the -reset headers, then anthropic-ratelimit-unified-reset, then the channel's claude_passive_usage sample (utilization ≥ 100, reset in the future, ≤ 8 days); otherwise a generic "usage limit reached, try later" (Codex today). Backend i18n en / zh-CN / zh-TW.
  • Switch on, nothing but keep-alive pings sent (helper.ResponseContentStarted): synchronous refund of the bound reservation (BillingSession.refundNow, same refunded flag as Refund), PreConsumeBilling again (route FellBack → wallet only), group back to OriginalGroup, Auto index 0 and GetRequestAutoGroups without the dedicated group, retry counter reset. Consume log other.subscription_fallback = {reason: bound_account_limited, subscription_id, from_group, to_group, limit_window} (admin-only subscription_fallback_channel_id), plus a WARN server log line.
  • Refund / idempotency: the subscription reservation is refunded through RefundSubscriptionPreConsume (request-id record → refunded); a second pre-consume with the same request id fails "already refunded"; the session's refunded flag stops the final RefundFailedRequestBilling from touching it again; the route is no longer active after the first fallback, so the wallet is reserved once. RefundSubscriptionPreConsume now applies the quota delta inside its own transaction instead of opening a nested one (the nested transaction deadlocked on a single-connection pool in the new tests).

Plan switch subscription_plans.fallback_to_shared_pool_on_limit (*bool, nil = false), admin create/update, drawer switch with description, 2 keys × 7 locales inserted in sort position by hand (no i18n:sync, no escaping changes).

  • Not snapshotted on UserSubscription, read from the plan (cached) when the limit is hit: the bound subscriptions in production already exist and there is no per-subscription editor, so a snapshot would leave the switch without effect for them; the switch only decides what happens to a request that would otherwise fail, and turning it off stops wallet charges immediately.

Research

Duplicate / prior art

Docs and code

  • https://docs.newapi.ai/ : subscription billing preference docs describe wallet/subscription order; no binding concept upstream.
  • https://deepwiki.com/QuantumNous/new-api : not consulted (fork-only feature).
  • README / repo docs: .agents/rules/billing.md read in full.
  • Code paths and what they imply for this change: NewBillingSession (source selection), PreConsumeUserSubscription / RefundSubscriptionPreConsume (idempotency), controller/relay.go retry loop + CacheGetRandomSatisfiedChannel (group used by retries), relay/responses_websocket.go (no Distribute → never steered), sub2api ratelimit_service.go isAnthropicWindowRejected / parseOpenAIRateLimitResetTime (read-only reference for triggers).

Alternatives considered

  • Option A: snapshot the switch per subscription like allow_wallet_overflow.
  • Option B: re-run full price estimation for the fallback group before the wallet reservation.
  • Why this approach: A would not reach existing bound subscriptions (see Change). B: the wallet reserves the same QuotaToPreConsume; settlement already uses the group ratio of the group that served the request (getChannel → HandleGroupRatio), and tiered billing re-reserves via PrepareTieredBillingForSelectedGroup, as for Auto cross-group retries.

Files

Path Why
middleware/distributor.go record SubscriptionRoute on steered requests
relay/common/relay_info.go, constant/context_key.go route type, context keys
model/subscription.go, model/main.go bound/unbound pre-consume, unbound checks, plan column (SQLite DDL list), refund in one transaction
model/subscription_route_binding.go ResolveSubscriptionRoute, SubscriptionFallsBackToSharedPool
service/billing_session.go, service/funding_source.go routed billing, bound-insufficient message, refundNow
service/subscription_route.go retry group, header capture, limit detection, fallback handler, limit error
service/group.go Auto without the dedicated group after fallback
service/log_info_generate.go subscription_fallback in consume log
controller/relay.go call the handler in the relay loop; retry group in relay and task loops
relay/channel/claude_oauth/adaptor.go, relay/channel/codex/adaptor.go, relay/helper/common.go keep limit headers; content-started check
controller/subscription.go plan create/update field
i18n/* backend messages
web/src/features/subscriptions/*, web/src/i18n/locales/* drawer switch, form mapping, 7 locales
service/subscription_route_test.go, middleware/distributor_test.go, model/subscription_channel_binding_test.go, web/.../plan-form.test.ts tests

Behavior

  • Before: see Issue facts.
  • After: see the table in Change.
  • Explicit non-goals / leftover work:
    • Async task path: retries stay in the dedicated group, routed billing applies through the shared NewBillingSession, but no limit fallback — tasks never reach a bindable channel (Claude OAuth / Codex have no task adaptor), so a task request is never steered in practice.
    • Responses WebSocket: /v1/responses WS does not go through Distribute, so it is never steered; only the unbound-subscription rules apply (covered by the billing tests). Steering WS traffic to the bound account is a separate change.
    • Codex reset time: generic message only (the 429 body's resets_at is not parsed).
    • If a user holds two bound subscriptions, only the newest routes (existing fix(subscription): route bound users per request instead of switching their group (HQ-Task T261105-13) #9 rule); the older one pays for nothing until the newest ends.

Verification

  • Commands and results (Windows, go1.26.10, Bun 1.4.0, worktree with placeholder web/dist/index.html):

    • GOWORK=off go build ./... → ok; relaykit/, tokenkit/ GOWORK=off go build ./... → ok; go vet ./model/ ./service/ ./middleware/ ./controller/ ./relay/... ./i18n/ ./constant/ → clean; gofmt -l → none.
    • GOWORK=off go test ./model/ ./service/ ./i18n/ ./relay/... -count=1 → all ok (relay, relay/channel, relay/channel/claude, codex, openai, relay/common, relay/helper, …).
    • go test ./service/ -run 'SubscriptionRoute|DetectSubscription|HandleSubscriptionRoute' -v → 8/8 PASS.
    • go test ./middleware/ → only TestAccessAndPanicLogsFollowLogRotation fails (known Windows TempDir cleanup); -run Distribute → 6/6 PASS.
    • go test ./controller/ → FAIL with 268 TempDir RemoveAll cleanup (audit.db) messages and 0 Error Trace lines (known pre-existing Windows failure).
    • web: bun install --frozen-lockfile; bun x --package @typescript/native-preview tsgo -b → no output; bun x vitest run → 212 files / 2530 tests passed; bun run build → ok; oxfmt on touched files; oxlint -c .oxlintrc.json src/features/subscriptions → only 2 pre-existing no-import-type-side-effects errors in untouched constants.ts / subscriptions-provider.tsx.
  • Manual steps and observed result (bgt, image new-api-fork:t261106-02 = 18356d4, container new-api-t10 @ 39688, SQLite, mock upstream new-api-t10-mock; channel feat(channel): Claude Subscription (OAuth) channel with usage and reset credits; Codex browser OAuth flow #1 OpenAI-type gpt-x,claude-y in default, channel chore: merge upstream main (72f3dc7da) into fork-main #2 Claude OAuth (fake key) claude-y bound to subscription feat(channel): Claude Subscription (OAuth) channel with usage and reset credits; Codex browser OAuth flow #1 of user 2 → claude-ch2; ModelPrice claude-y $0.01 = 5000, gpt-x $0.02 = 10000; wallet 1,000,000):

    Step Response Wallet Δ Bound sub used Δ Consume log
    S1 claude-y, default token 200 from channel 2 0 +5000 ch 2, group claude-ch2, billing_source subscription, subscription_id 1
    S2 gpt-x 200 from channel 1 −10000 0 ch 1, default, wallet
    S3 claude-y + mock 429 (5h rejected), switch off 429 订阅账号的 5 小时额度已用尽,将于 2026-11-06 16:25 EST 重置 0 0 (reserved, refunded) none
    S4 same, switch on, default token 200 from channel 1 −5000 0 ch 1, default, wallet, subscription_fallback {from claude-ch2, to default, limit_window 5h}
    S5 same, switch on, Auto token 200 from channel 1 −5000 0 ch 1, default, wallet, subscription_fallback {to auto}
    S6 claude-y normal, Auto token 200 from channel 2 0 +5000 ch 2, claude-ch2, subscription

    Server log for S4 (one request id): 需要预扣费 $0.010000 (funding=subscription) → 渠道 #2,状态码 429 → subscription 1 bound account (channel #2) hit its usage limit (window="5h"); falling back to the shared pool group default, billed to the wallet → 需要预扣费 $0.010000 (funding=wallet) → consume log channel 1.

  • UI: none (drawer switch covered by plan-form.test.ts; plan updates in the walkthrough went through PUT /api/subscription/admin/plans/1 and read back fallback_to_shared_pool_on_limit true/false).

  • Tests added or updated, or why none: service/subscription_route_test.go (new: attribution table incl. wallet_first/wallet_only, bound short without wallet, overflow with bound/unbound subscriptions, limit detection table, fallback off/on/Auto/keep-account cases, refund idempotency, consume-log marker); middleware/distributor_test.go (route recorded with original group); model/subscription_channel_binding_test.go (rename); web/.../plan-form.test.ts.

  • Databases / providers / platforms exercised:

    • SQLite (container): fresh start + 2 restarts; upgrade of a DB created by new-api-fork:fork-main-fe07a0240 (production build) then 2 starts of this image → fallback_to_shared_pool_on_limit numeric DEFAULT 0, no error lines.
    • PostgreSQL 17.11 (postgres:17-alpine): start on the production build, then this image twice → fallback_to_shared_pool_on_limit boolean, nullable, no default; no error lines in startup logs.
    • Providers: mock Anthropic Messages (Claude OAuth adaptor) and mock OpenAI chat.
  • Not verified:

    • MySQL: docker pull mysql:8.0 on bgt fails with the Docker Desktop credential helper ("A specified logon session does not exist") even with an empty DOCKER_CONFIG; no MySQL image is present. The column is a plain nullable *bool without a GORM default (same shape as allow_wallet_overflow minus its default), so no repeated ALTER is expected, but this is not run.
    • Upgrade with existing plan rows on PostgreSQL (the upgraded DB had no plans; existing rows get NULL → read as false).
    • Streaming request hitting the limit (non-stream only in Docker; the content-started check is unit-level).
    • Real Claude / Codex accounts, Codex 429 shape, Redis cache path, multi-instance.

Risks

  • Failure modes: a 429 from the bound channel that is not an account limit (e.g. Anthropic overload answered as 429) also ends the request (switch off) or falls back (switch on); before this PR it would have retried inside the dedicated group or leaked to the token group. Detection runs only for steered requests on the bound channel.
  • Billing / quota / auth impact: bound subscriptions stop paying for non-bound models (users with only a bound subscription now pay those from the wallet — intended); routed requests ignore the user's billing preference; with the switch on, wallet is charged at the fallback group's ratio.
  • Follow-ups: steer Responses WebSocket traffic; parse Codex reset time; MySQL verification.

Scope check

  • Single focused change: yes
  • Secrets included: no
  • Out of scope (Coding Plan / reverse-engineered channel / third-party wrapper / Codex / pass-through-only forwarding): no

🤖 Generated with Claude Code

…optional shared-pool fallback (HQ-Task T261106-02)

A subscription bound to an OAuth channel account now pays only for the
requests the distributor steers to that account, and those requests are
billed to that subscription alone:

- distributor records the binding (subscription, channel, dedicated group,
  original group) on every steered request; billing then pre-consumes from
  that subscription only (PreConsumeBoundUserSubscription), ignoring the
  billing preference and never overflowing to the wallet
- every other request skips subscriptions with a bound channel
  (pre-consume candidates, HasActiveUnboundUserSubscription,
  UserActiveUnboundSubscriptionsAllowWalletOverflow); a user with only a
  bound subscription pays other models from the wallet
- retries of a steered request stay in the dedicated group instead of
  falling back to the token group

New plan switch fallback_to_shared_pool_on_limit (default off, read from the
plan when the limit is hit). When the bound account answers with its own
usage limit (429, rate_limit_error, unified-*-status rejected, Codex
usage_limit_reached) before anything reached the client:
- off: the request ends with a 429 naming the exhausted window and its reset
  time (response headers first, then the channel's passive usage sample)
- on: the subscription reservation is refunded synchronously, the wallet
  reserves the request, and the retry continues in the original group (Auto
  without the dedicated group); the consume log carries
  subscription_fallback

RefundSubscriptionPreConsume now applies the quota delta inside its own
transaction instead of opening a nested one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AdoreJc
AdoreJc merged commit 80deef0 into fork-main Nov 6, 2026
2 checks passed
@AdoreJc
AdoreJc deleted the hq/T261106-02-subscription-billing-fallback branch November 14, 2026 10:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant