fix(billing): make a namespace's subscription an optional object

[otavio]

Pairs with shellhub-io/cloud#2510 (same branch name). Neither side builds without the other.

Why

On Cloud, a namespace that added a payment method but never completed checkout could accept no device and open no SSH session, and the API called it device limit reached. Its free allowance was not reduced — it was zero. See shellhub-io/team#214 for the production analysis: 124 namespaces, 118 accepted devices unreachable.

The cause is in this repo's model. Billing.Status had to carry two unrelated facts: whether a subscription exists at all, and how it is doing. Customer creation wrote inactive there, and every reader had to guess which fact the value meant.

What changes

The subscription becomes an optional object (pkg/models/billing.go).

type Billing struct {
    CustomerID   string
    Subscription *BillingSubscription  // nil = checkout never completed
    CreatedAt, UpdatedAt string
}

• BillingStatusInactive is gone. No subscription means no status, so the ambiguous state cannot be written.
• The stored Active boolean is gone. It duplicated Status.IsActive() at five write sites and could drift from the status it mirrored; IsActive() derives it now.
• Clone() deep-copies. The webhook handlers used billing := *namespace.Billing, which with a pointer field would share the subscription with the namespace and mutate it.
• HasCutomer is spelled HasCustomer.

Device acceptance stops lying (server/api/services/). BillingEvaluation now names the rule that denied the device, and the two denials get different errors:

Denial	Error	Console copy
Namespace used its whole allowance	ErrDeviceLimit	free a slot or upgrade
Subscription denies the device	ErrDeviceBillingBlocked	finish or repair the subscription; the device count is not the problem

Both stay HTTP 402. The customer in the report deleted all three of their devices because the old message told them to.

Observability (server/ssh/). The banner handler logged a firewall block and a billing block under one message, which made the incident readable only by grouping on the error text. Each case now has its own message, and both carry the tenant. EvaluateBilling logs the block reason.

API contract. namespaceBilling follows the model: subscription nested and optional, active removed, timestamps optional. billingStatus keeps inactive, because that enum is shared with the payment-gateway subscription schema, where the console uses it as its own "no subscription" placeholder.

Test plan

• go test ./... — server/ and root: pass. New: TestValidateBillingForDeviceAcceptance, TestErrDeviceBillingBlocked.
• golangci-lint run ./... — 0 issues in both modules.
• go mod tidy — no drift.
• Console npm run build, lint, test — pass, 3149 tests.

Deploy note

Cloud carries migration 003, which reshapes the stored records. It runs at store construction, under a lock, before the server serves. During a rolling deploy an old replica that reads a migrated row sees an empty status and applies the free-tier math, so the window locks nobody out.

[github-actions]

Code Review Complete

The automated review ran but did not post an updated summary — this usually means no new issues were found since the previous review. If you've pushed changes and want a fresh pass, comment /review.

View job