3x-ui/internal/sub
Namso9 89ee1242bd
feat(sub): add read-only HWID device-slot status endpoint (#6380)
* feat(sub): add read-only HWID device-slot status endpoint

Closes #6357

A client with an HWID limit had no way to tell a subscriber how many device
slots were left: /{subPath}/{subId} only exposes the gate as a boolean through
X-Hwid-* headers on a 404, and ?format=info carries no limitHwid or registered
count. Every "why can't I connect on my new phone" case therefore had to be
answered by the operator by hand.

GET /{subPath}/{subId}/hwid-status now returns the aggregate counters:

  {"active":true,"limit":2,"registered":1,"remaining":1,"full":false}

- SELECT-only. It never registers an hwid, never touches last_seen and never
  calls the enforcement path, so asking about a slot cannot spend one.
- Counters only: no hwid value or hash, no email, no device metadata, no IP,
  no User-Agent, and none of the X-Hwid-* gate headers.
- The subscription id is already the bearer secret for /{subPath}/{subId}, so
  no admin token and no new auth mechanism.
- Unknown and disabled subscriptions both answer a bare 404, with identical
  status, headers and body, so the route cannot be used to probe which
  subscription ids exist.
- No HWID limit configured returns {"active":false,"limit":0,...}.
- No schema change and no migration.

Scoped to enabled clients exactly like effectiveHwidLimitForSubID, so the
reported limit is always the limit the gate enforces on a shared sub_id, and
remaining clamps at zero when the effective limit drops below the number of
registered devices. A separate route leaves /{subPath}/{subId}, ?format=info
and the JSON/Clash routes byte-for-byte unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(sub): document hwid-status as the bare object it returns

The OpenAPI operation for GET /{subPath}/{subId}/hwid-status inherited the
{success,msg,obj} panel envelope from build-openapi.mjs's default 200
response, while the handler writes the HwidSlotStatus struct bare. A client
generated from the spec would read `obj` and never find the counters, and
the description prose contradicted the schema with a hand-written example.

HwidSlotStatus now sits in openapigen's StructAllow with example: tags, the
entry references the generated schema through a `responses` block, and
build-openapi.mjs attaches the generated example to any `responses` entry
that $refs a generated schema, so no example is hand-written. The HEAD
variant the controller registers is documented like its siblings, and the
summary follows the "path prefix is configured by subPath" wording now that
fresh panels randomise the prefix.

Regenerated frontend/public/openapi.json, docs/public/openapi.json and the
subscription-server MDX. openapi-runtime-contracts.test.ts pins the bare
schema, the generated example and the HEAD operation.

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-11 11:59:35 +02:00
..
build_urls_test.go fix: resolve a batch of open bug-tagged issues (traffic accounting, share strategy, sub address, CPU) (#5477) 2026-06-22 00:22:28 +02:00
characterization_test.go fix(sub): restore client email in panel copy/QR link remark (#5532) 2026-06-24 15:25:41 +02:00
clash_external.go refactor(frontend): move form-item hints from extra to tooltip 2026-06-17 17:24:16 +02:00
clash_info_node_test.go feat(sub): add dummy info node and status configs for subscriptions (#6412) 2026-09-08 17:14:01 +02:00
clash_service.go feat(clients): let admins set PersistentKeepalive on tunnel clients (#6377) 2026-09-10 22:32:42 +02:00
clash_service_test.go feat(clients): let admins set PersistentKeepalive on tunnel clients (#6377) 2026-09-10 22:32:42 +02:00
clash_yaml.go style: drop the line comments added with the triage fixes 2026-07-27 14:37:57 +02:00
clash_yaml_test.go style: drop the line comments added with the triage fixes 2026-07-27 14:37:57 +02:00
controller.go feat(sub): add read-only HWID device-slot status endpoint (#6380) 2026-09-11 11:59:35 +02:00
controller_test.go feat(sub): add legacy Clash subscription endpoint (#6338) 2026-09-10 21:58:55 +02:00
default.json fix(sub): bind JSON local inbounds to 127.0.0.1 and keep mux.cool off Vision outbounds (#6418) 2026-09-05 20:44:48 +02:00
dist.go feat(sub): add raw subscription download actions (#6017) 2026-07-21 15:52:33 +02:00
endpoint.go fix(sub): drop Reality parameters when a host forces plain TLS 2026-09-09 00:37:31 +02:00
endpoint_test.go feat(sub): add Happ client integration, routing presets, and app management (#6434) 2026-09-10 15:46:12 +02:00
export_all_links_test.go feat(inbounds): apply remark template to Export all inbound links 2026-06-27 11:22:45 +02:00
external_config.go Feature/fix external subscription client expiry (#6333) 2026-09-03 22:32:05 +02:00
external_config_test.go Add per-client external link controls (#5650) 2026-08-18 13:55:04 +02:00
external_only_sub_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
external_subscription.go Add per-client external link controls (#5650) 2026-08-18 13:55:04 +02:00
external_subscription_test.go Add per-client external link controls (#5650) 2026-08-18 13:55:04 +02:00
forwarded_trust.go fix(sub): honor trustedProxyCIDRs before forwarded URLs (#6135) 2026-07-29 21:01:59 +02:00
forwarded_trust_test.go chore: refresh dependencies and modernize Go test idioms 2026-07-30 03:14:22 +02:00
happ.go feat(sub): add Happ client integration, routing presets, and app management (#6434) 2026-09-10 15:46:12 +02:00
happ_test.go feat(sub): add Happ client integration, routing presets, and app management (#6434) 2026-09-10 15:46:12 +02:00
host_sub.go Bug-label issue sweep: 16 fixes (#6083) 2026-07-23 15:34:42 +02:00
host_sub_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
hwid_controller_test.go feat(sub): add read-only HWID device-slot status endpoint (#6380) 2026-09-11 11:59:35 +02:00
hysteria_geco_uri_test.go fix(hysteria): standard geco share links and persistent uTLS None (#6325) 2026-09-03 16:35:07 +02:00
inactive_external_sub_test.go Feature/fix external subscription client expiry (#6333) 2026-09-03 22:32:05 +02:00
info_endpoint_test.go fix(sub): restore the subscription info page for browser visits 2026-08-15 22:11:37 +02:00
json_flow_gate_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
json_info_node_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
json_routing.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
json_routing_baked_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
json_routing_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
json_service.go feat(clients): let admins set PersistentKeepalive on tunnel clients (#6377) 2026-09-10 22:32:42 +02:00
json_service_test.go feat(clients): let admins set PersistentKeepalive on tunnel clients (#6377) 2026-09-10 22:32:42 +02:00
links.go fix(mtproto): use hosts for public share links (#6369) 2026-09-08 15:36:57 +02:00
links_test.go fix(mtproto): use hosts for public share links (#6369) 2026-09-08 15:36:57 +02:00
mutation_audit_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
page_data_test.go feat(sub): expose live online status and add ?format=info endpoint 2026-07-23 23:57:29 +02:00
placeholders.go feat(sub): add template variables to subscription metadata (#6163) 2026-08-15 17:38:29 +02:00
placeholders_test.go feat(sub): add template variables to subscription metadata (#6163) 2026-08-15 17:38:29 +02:00
remark_vars.go feat(sub): add dummy info node and status configs for subscriptions (#6412) 2026-09-08 17:14:01 +02:00
remark_vars_test.go fix(sub): use a fullwidth percent in USAGE_PERCENTAGE (#6174) 2026-08-14 20:13:15 +02:00
remote_routing.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
remote_routing_test.go fix(hysteria): standard geco share links and persistent uTLS None (#6325) 2026-09-03 16:35:07 +02:00
salamander_uri_test.go fix(hysteria): standard geco share links and persistent uTLS None (#6325) 2026-09-03 16:35:07 +02:00
service.go feat(clients): let admins set PersistentKeepalive on tunnel clients (#6377) 2026-09-10 22:32:42 +02:00
service_amneziawg_test.go feat(clients): let admins set PersistentKeepalive on tunnel clients (#6377) 2026-09-10 22:32:42 +02:00
service_dedup_test.go fix(sub): resolve subscription clients and stats from normalized tables 2026-07-02 16:58:00 +02:00
service_flow_test.go feat(inbound): DisableFlow — opt an inbound out of auto XTLS Vision (#5689) (#5698) 2026-08-15 23:09:16 +02:00
service_info_node_test.go feat(sub): add dummy info node and status configs for subscriptions (#6412) 2026-09-08 17:14:01 +02:00
service_mtproto_test.go fix(mtproto): use hosts for public share links (#6369) 2026-09-08 15:36:57 +02:00
service_orphaned_stats_test.go chore: bump deps and modernize test loops 2026-06-26 00:10:30 +02:00
service_property_test.go fix(nodes): stop multi-attached client traffic inflating across node inbounds 2026-06-15 19:31:57 +02:00
service_sharelink_test.go feat(reality): derive a stable per-client spiderX for shared links 2026-07-02 12:53:08 +02:00
service_sort_test.go feat(hosts): managed Hosts for per-host subscription link overrides (#5409) 2026-06-17 12:06:55 +02:00
service_test.go feat(xray): update xray-core to v26.9.9 and follow the udpHop move 2026-09-09 01:53:00 +02:00
service_userinfo_test.go refactor: focused service files, leaf subpackages, and an internal/ layout (#5167) 2026-06-10 15:19:22 +02:00
service_wireguard_test.go fix(wireguard): preserve all Allowed IPs in share link, .conf, and subscription (#6051) 2026-07-21 15:50:16 +02:00
sub.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
sub_balancer_protocol_tag_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
sub_balancer_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
sub_fetch_test.go feat(sub): expose last subscription fetch time (#6217) 2026-08-15 15:22:11 +02:00
sub_json_observatory_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
sub_panic_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
sub_scale_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
vless_route.go fix(sub): bake Host VLESS Route into subscription UUIDs 2026-06-29 14:32:23 +02:00
vless_route_sub_test.go feat(sub): bake Happ/INCY routing profiles into the JSON subscription (#6402) 2026-09-10 17:05:54 +02:00
vless_route_test.go fix(sub): bake Host VLESS Route into subscription UUIDs 2026-06-29 14:32:23 +02:00