xinyin025/3x-ui
1
0
Fork 0
mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-09-16 15:17:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(sub): add read-only HWID device-slot status endpoint (#6380)

Browse Source 
* 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>
This commit is contained in:
Namso9
2026-09-11 16:29:35 +06:30
committed by GitHub
parent 8f162994ef
commit 89ee1242bd
15 changed files with 637 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/public/openapi.json
+126
View File
@@ -2492,6 +2492,39 @@
],
"type": "object"
},
"HwidSlotStatus": {
"description": "HwidSlotStatus is the aggregate device-slot view exposed to subscribers:\ncounters only, no hwid value or hash, no email, no device metadata.",
"properties": {
"active": {
"example": true,
"type": "boolean"
},
"full": {
"example": false,
"type": "boolean"
},
"limit": {
"example": 2,
"type": "integer"
},
"registered": {
"example": 1,
"type": "integer"
},
"remaining": {
"example": 1,
"type": "integer"
}
},
"required": [
"active",
"full",
"limit",
"registered",
"remaining"
],
"type": "object"
},
"Inbound": {
"description": "Inbound represents an Xray inbound configuration with traffic statistics and settings.",
"properties": {
@@ -14404,6 +14437,99 @@
}
}
},
"/{subPath}{subid}/hwid-status": {
"get": {
"tags": [
"Subscription Server"
],
"summary": "Return aggregate HWID device-slot usage for the subscription: whether an HWID limit is active, the limit, how many devices are registered and how many slots remain. Read-only — it never registers a device, so asking does not consume a slot. Counters only: no HWID value, email or device metadata. The path prefix is configured by subPath.",
"operationId": "get_subPath_subid_hwid_status",
"description": "Responds with the bare HwidSlotStatus object, not the <code>{success,msg,obj}</code> panel envelope, like the other subscription-server routes. With no HWID limit configured, <code>active</code> is false and every counter is 0.",
"parameters": [
{
"name": "subid",
"in": "path",
"required": true,
"description": "Client subscription ID.",
"schema": {
"type": "string"
}
},
{
"name": "subPath",
"in": "path",
"required": true,
"description": "",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device-slot counters for the subscription.",
"content": {
"application/json": {
"example": {
"active": true,
"full": false,
"limit": 2,
"registered": 1,
"remaining": 1
},
"schema": {
"$ref": "#/components/schemas/HwidSlotStatus"
}
}
}
},
"404": {
"description": "No enabled client matches the subscription ID. Empty body."
},
"500": {
"description": "Database lookup failed. Empty body."
}
}
},
"head": {
"tags": [
"Subscription Server"
],
"summary": "Return the HWID device-slot status code and headers as GET without a response body.",
"operationId": "head_subPath_subid_hwid_status",
"parameters": [
{
"name": "subid",
"in": "path",
"required": true,
"description": "Client subscription ID.",
"schema": {
"type": "string"
}
},
{
"name": "subPath",
"in": "path",
"required": true,
"description": "",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Headers match GET; no response body."
},
"404": {
"description": "No enabled client matches the subscription ID. Empty body."
},
"500": {
"description": "Database lookup failed. Empty body."
}
}
}
},
"/{jsonPath}{subid}": {
"get": {
"tags": [
frontend/scripts/build-openapi.mjs
+18 -1
View File
@@ -112,6 +112,21 @@ function paramToOpenApi(p) {
return out;
}
// A `responses` entry that $refs a generated schema takes its example from the
// Go `example:` tags, the same source responseSchema uses — never hand-written.
function withGeneratedExample(ep, code, res) {
const json = res.content?.['application/json'];
const name = json?.schema?.$ref?.replace('#/components/schemas/', '');
if (!name) return res;
if (SCHEMAS[name] === undefined || EXAMPLES[name] === undefined) {
throw new Error(`${ep.method} ${ep.path}: ${code} response schema "${name}" is not generated`);
}
return {
...res,
content: { ...res.content, 'application/json': { example: EXAMPLES[name], ...json } },
};
}
function buildOperation(ep, tag) {
const op = {
tags: [tag],
@@ -257,7 +272,9 @@ function buildOperation(ep, tag) {
}
}
if (ep.responses) {
Object.assign(responses, ep.responses);
for (const [code, res] of Object.entries(ep.responses)) {
responses[code] = withGeneratedExample(ep, code, res);
}
} else {
responses['200'] = {
description: 'Successful response',
frontend/src/generated/examples.ts
+7
View File
@@ -644,6 +644,13 @@ export const EXAMPLES: Record<string, unknown> = {
"verifyPeerCertByName": "",
"vlessRoute": ""
},
"HwidSlotStatus": {
"active": true,
"full": false,
"limit": 2,
"registered": 1,
"remaining": 1
},
"Inbound": {
"clientStats": [
{
frontend/src/generated/schemas.ts
+33
View File
@@ -2466,6 +2466,39 @@ export const SCHEMAS: Record<string, unknown> = {
],
"type": "object"
},
"HwidSlotStatus": {
"description": "HwidSlotStatus is the aggregate device-slot view exposed to subscribers:\ncounters only, no hwid value or hash, no email, no device metadata.",
"properties": {
"active": {
"example": true,
"type": "boolean"
},
"full": {
"example": false,
"type": "boolean"
},
"limit": {
"example": 2,
"type": "integer"
},
"registered": {
"example": 1,
"type": "integer"
},
"remaining": {
"example": 1,
"type": "integer"
}
},
"required": [
"active",
"full",
"limit",
"registered",
"remaining"
],
"type": "object"
},
"Inbound": {
"description": "Inbound represents an Xray inbound configuration with traffic statistics and settings.",
"properties": {
frontend/src/generated/types.ts
+8
View File
@@ -570,6 +570,14 @@ export interface HostGroup {
vlessRoute: string;
}
export interface HwidSlotStatus {
active: boolean;
full: boolean;
limit: number;
registered: number;
remaining: number;
}
export interface Inbound {
clientStats: ClientTraffic[];
disableFlow: boolean;
frontend/src/generated/zod.ts
+9
View File
@@ -609,6 +609,15 @@ export const HostGroupSchema = z.object({
});
export type HostGroup = z.infer<typeof HostGroupSchema>;
export const HwidSlotStatusSchema = z.object({
active: z.boolean(),
full: z.boolean(),
limit: z.number().int(),
registered: z.number().int(),
remaining: z.number().int(),
});
export type HwidSlotStatus = z.infer<typeof HwidSlotStatusSchema>;
export const InboundSchema = z.object({
clientStats: z.array(z.lazy(() => ClientTrafficSchema)),
disableFlow: z.boolean(),
frontend/src/pages/api-docs/endpoints.ts
+34
View File
@@ -183,6 +183,11 @@ const subscriptionHeadResponses = {
'500': { description: 'Subscription generation failed.' },
};
const hwidStatusErrorResponses = {
'404': { description: 'No enabled client matches the subscription ID. Empty body.' },
'500': { description: 'Database lookup failed. Empty body.' },
};
export const sections: readonly Section[] = [
{
id: 'authentication',
@@ -2618,6 +2623,35 @@ export const sections: readonly Section[] = [
params: [{ name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' }],
responses: subscriptionHeadResponses,
},
{
method: 'GET',
path: '/{subPath}:subid/hwid-status',
summary:
'Return aggregate HWID device-slot usage for the subscription: whether an HWID limit is active, the limit, how many devices are registered and how many slots remain. Read-only — it never registers a device, so asking does not consume a slot. Counters only: no HWID value, email or device metadata. The path prefix is configured by subPath.',
description:
'Responds with the bare HwidSlotStatus object, not the <code>{success,msg,obj}</code> panel envelope, like the other subscription-server routes. With no HWID limit configured, <code>active</code> is false and every counter is 0.',
params: [{ name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' }],
responses: {
'200': {
description: 'Device-slot counters for the subscription.',
content: {
'application/json': { schema: { $ref: '#/components/schemas/HwidSlotStatus' } },
},
},
...hwidStatusErrorResponses,
},
},
{
method: 'HEAD',
path: '/{subPath}:subid/hwid-status',
summary:
'Return the HWID device-slot status code and headers as GET without a response body.',
params: [{ name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' }],
responses: {
'200': { description: 'Headers match GET; no response body.' },
...hwidStatusErrorResponses,
},
},
{
method: 'GET',
path: '/{jsonPath}:subid',
frontend/src/test/openapi-runtime-contracts.test.ts
+15
View File
@@ -241,4 +241,19 @@ describe('generated OpenAPI runtime contracts', () => {
expect(operation('/{jsonPath}{subid}', 'head')).toBeDefined();
expect(operation('/{clashPath}{subid}', 'head')).toBeDefined();
});
it('documents the HWID slot status as a bare generated object, not the panel envelope', () => {
const path = '/{subPath}{subid}/hwid-status';
const json = operation(path, 'get').responses['200'].content?.['application/json'];
expect(json?.schema).toEqual({ $ref: '#/components/schemas/HwidSlotStatus' });
expect(json?.example).toEqual(EXAMPLES.HwidSlotStatus);
expect(spec.components.schemas.HwidSlotStatus.required).toEqual([
'active',
'full',
'limit',
'registered',
'remaining',
]);
expect(operation(path, 'head')).toBeDefined();
});
});