Repository navigation
feat(subscription): bill bound subscriptions only for their account, optional shared-pool fallback (HQ-Task T261106-02) - #11
Merged
Conversation
…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>
1 of 5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
HQ-Task: T261106-02
Agent
Links
User request
Out of scope — refuse
fork-main, not upstream)Open gate — do not open unless all are satisfied
go buildor tests passed: yesKind
Issue facts
PreConsumeUserSubscriptiontakes 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 preferencewallet_first/wallet_onlymakes even bound-account requests pay from the wallet. Retries of a steered request select fromrelayInfo.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.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)subscription_first/subscription_only/wallet_first/wallet_only)insufficient_user_quota"绑定账号的订阅额度不足:剩余 X,需要 Y"; never the wallet, never another subscriptionallow_wallet_overflowdecisionsubscription_first/wallet_*subscription_onlymiddleware/distributor.gorecordsrelaycommon.SubscriptionRoute{SubscriptionId, ChannelId, Group, OriginalGroup}on every steered request (also when the token already uses the dedicated group);GenRelayInfocopies it toRelayInfo.SubscriptionRoute.model.ResolveSubscriptionRouteGroupbecameResolveSubscriptionRoute(returns the binding).model.PreConsumeBoundUserSubscription(requestId, userId, subscriptionId, amount); it andPreConsumeUserSubscriptionshare one transaction body (idempotent request record, row lock,maybeResetUserSubscriptionWithPlanTx). Unbound =COALESCE(bound_channel_id, 0) = 0. RenamedHasActiveUnboundUserSubscription,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)rate_limit_error/usage_limit_reached/rate_limit_exceeded,anthropic-ratelimit-unified-status: rejected, or anyanthropic-ratelimit-unified-{5h,7d,7d_oi}-status: rejected/ utilization ≥ 1. The Claude OAuth and Codex adaptors keep the answer'santhropic-ratelimit-unified-*/x-codex-*/retry-afterheaders on the request for this check.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-resetheaders, thenanthropic-ratelimit-unified-reset, then the channel'sclaude_passive_usagesample (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.helper.ResponseContentStarted): synchronous refund of the bound reservation (BillingSession.refundNow, samerefundedflag asRefund),PreConsumeBillingagain (routeFellBack→ wallet only), group back toOriginalGroup, Auto index 0 andGetRequestAutoGroupswithout the dedicated group, retry counter reset. Consume logother.subscription_fallback = {reason: bound_account_limited, subscription_id, from_group, to_group, limit_window}(admin-onlysubscription_fallback_channel_id), plus a WARN server log line.RefundSubscriptionPreConsume(request-id record →refunded); a second pre-consume with the same request id fails "already refunded"; the session'srefundedflag stops the finalRefundFailedRequestBillingfrom touching it again; the route is no longer active after the first fallback, so the wallet is reserved once.RefundSubscriptionPreConsumenow 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 (noi18n:sync, no escaping changes).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
.agents/rules/billing.mdread in full.NewBillingSession(source selection),PreConsumeUserSubscription/RefundSubscriptionPreConsume(idempotency),controller/relay.goretry loop +CacheGetRandomSatisfiedChannel(group used by retries),relay/responses_websocket.go(no Distribute → never steered), sub2apiratelimit_service.goisAnthropicWindowRejected/parseOpenAIRateLimitResetTime(read-only reference for triggers).Alternatives considered
allow_wallet_overflow.QuotaToPreConsume; settlement already uses the group ratio of the group that served the request (getChannel→HandleGroupRatio), and tiered billing re-reserves viaPrepareTieredBillingForSelectedGroup, as for Auto cross-group retries.Files
middleware/distributor.goSubscriptionRouteon steered requestsrelay/common/relay_info.go,constant/context_key.gomodel/subscription.go,model/main.gomodel/subscription_route_binding.goResolveSubscriptionRoute,SubscriptionFallsBackToSharedPoolservice/billing_session.go,service/funding_source.gorefundNowservice/subscription_route.goservice/group.goservice/log_info_generate.gosubscription_fallbackin consume logcontroller/relay.gorelay/channel/claude_oauth/adaptor.go,relay/channel/codex/adaptor.go,relay/helper/common.gocontroller/subscription.goi18n/*web/src/features/subscriptions/*,web/src/i18n/locales/*service/subscription_route_test.go,middleware/distributor_test.go,model/subscription_channel_binding_test.go,web/.../plan-form.test.tsBehavior
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./v1/responsesWS does not go throughDistribute, 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.resets_atis not parsed).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→ allok(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/→ onlyTestAccessAndPanicLogsFollowLogRotationfails (known Windows TempDir cleanup);-run Distribute→ 6/6 PASS.go test ./controller/→ FAIL with 268TempDir RemoveAll cleanup(audit.db) messages and 0Error Tracelines (known pre-existing Windows failure).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;oxfmton touched files;oxlint -c .oxlintrc.json src/features/subscriptions→ only 2 pre-existingno-import-type-side-effectserrors in untouchedconstants.ts/subscriptions-provider.tsx.Manual steps and observed result (bgt, image
new-api-fork:t261106-02= 18356d4, containernew-api-t10@ 39688, SQLite, mock upstreamnew-api-t10-mock; channel feat(channel): Claude Subscription (OAuth) channel with usage and reset credits; Codex browser OAuth flow #1 OpenAI-typegpt-x,claude-yindefault, channel chore: merge upstream main (72f3dc7da) into fork-main #2 Claude OAuth (fake key)claude-ybound 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):订阅账号的 5 小时额度已用尽,将于 2026-11-06 16:25 EST 重置subscription_fallback {from claude-ch2, to default, limit_window 5h}subscription_fallback {to auto}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 throughPUT /api/subscription/admin/plans/1and read backfallback_to_shared_pool_on_limittrue/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:
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.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.Not verified:
docker pull mysql:8.0on bgt fails with the Docker Desktop credential helper ("A specified logon session does not exist") even with an emptyDOCKER_CONFIG; no MySQL image is present. The column is a plain nullable*boolwithout a GORM default (same shape asallow_wallet_overflowminus its default), so no repeatedALTERis expected, but this is not run.Risks
Scope check
🤖 Generated with Claude Code