mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-18 03:45:02 +03:00
Namso9
89ee1242bd
* 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>
110 lines
8.7 KiB
Plaintext
110 lines
8.7 KiB
Plaintext
---
|
|
title: Subscription Server
|
|
description: A separate HTTP/HTTPS server that serves proxy subscription links
|
|
(standard, JSON, and Clash) to clients. The server listens on its own port
|
|
(default 2096) and is configured in Settings → Subscription. Fresh panels
|
|
generate random path prefixes for each format; all paths remain configurable.
|
|
Every subscription endpoint sets response headers for client apps to read
|
|
traffic/expiry info.
|
|
full: true
|
|
_openapi:
|
|
preload:
|
|
- ./public/openapi.json
|
|
toc:
|
|
- depth: 2
|
|
title: 'Return base64-encoded subscription links for all enabled clients
|
|
matching the subscription ID. When the request has an Accept: text/html
|
|
header or ?html=1, renders a styled info page instead. With
|
|
?format=info, returns the page view-model as JSON (traffic, expiry,
|
|
online status; no links) for live polling. The path prefix is configured
|
|
by subPath.'
|
|
url: '#return-base64-encoded-subscription-links-for-all-enabled-clients-matching-the-subscription-id-when-the-request-has-an-accept-texthtml-header-or-html1-renders-a-styled-info-page-instead-with-formatinfo-returns-the-page-view-model-as-json-traffic-expiry-online-status-no-links-for-live-polling-the-path-prefix-is-configured-by-subpath'
|
|
- depth: 2
|
|
title: Return the same status and subscription metadata headers as GET without a
|
|
response body.
|
|
url: '#return-the-same-status-and-subscription-metadata-headers-as-get-without-a-response-body'
|
|
- depth: 2
|
|
title: '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.'
|
|
url: '#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'
|
|
- depth: 2
|
|
title: Return the HWID device-slot status code and headers as GET without a
|
|
response body.
|
|
url: '#return-the-hwid-device-slot-status-code-and-headers-as-get-without-a-response-body'
|
|
- depth: 2
|
|
title: Return subscription as a JSON array of proxy configs (one per enabled
|
|
client). Only when JSON subscription is enabled in settings. The path
|
|
prefix is configured by subJsonPath.
|
|
url: '#return-subscription-as-a-json-array-of-proxy-configs-one-per-enabled-client-only-when-json-subscription-is-enabled-in-settings-the-path-prefix-is-configured-by-subjsonpath'
|
|
- depth: 2
|
|
title: Return the JSON subscription status and metadata headers without a body.
|
|
Registered only when JSON subscriptions are enabled.
|
|
url: '#return-the-json-subscription-status-and-metadata-headers-without-a-body-registered-only-when-json-subscriptions-are-enabled'
|
|
- depth: 2
|
|
title: Return subscription as a Clash/Mihomo-compatible YAML config, including
|
|
configured global Clash routing rules. Only when Clash subscription is
|
|
enabled in settings. The path prefix is configured by subClashPath.
|
|
url: '#return-subscription-as-a-clashmihomo-compatible-yaml-config-including-configured-global-clash-routing-rules-only-when-clash-subscription-is-enabled-in-settings-the-path-prefix-is-configured-by-subclashpath'
|
|
- depth: 2
|
|
title: Return the Clash subscription status and metadata headers without a body.
|
|
Registered only when Clash subscriptions are enabled.
|
|
url: '#return-the-clash-subscription-status-and-metadata-headers-without-a-body-registered-only-when-clash-subscriptions-are-enabled'
|
|
structuredData:
|
|
headings:
|
|
- content: 'Return base64-encoded subscription links for all enabled clients
|
|
matching the subscription ID. When the request has an Accept:
|
|
text/html header or ?html=1, renders a styled info page instead. With
|
|
?format=info, returns the page view-model as JSON (traffic, expiry,
|
|
online status; no links) for live polling. The path prefix is
|
|
configured by subPath.'
|
|
id: return-base64-encoded-subscription-links-for-all-enabled-clients-matching-the-subscription-id-when-the-request-has-an-accept-texthtml-header-or-html1-renders-a-styled-info-page-instead-with-formatinfo-returns-the-page-view-model-as-json-traffic-expiry-online-status-no-links-for-live-polling-the-path-prefix-is-configured-by-subpath
|
|
- content: Return the same status and subscription metadata headers as GET without
|
|
a response body.
|
|
id: return-the-same-status-and-subscription-metadata-headers-as-get-without-a-response-body
|
|
- content: '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.'
|
|
id: 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
|
|
- content: Return the HWID device-slot status code and headers as GET without a
|
|
response body.
|
|
id: return-the-hwid-device-slot-status-code-and-headers-as-get-without-a-response-body
|
|
- content: Return subscription as a JSON array of proxy configs (one per enabled
|
|
client). Only when JSON subscription is enabled in settings. The path
|
|
prefix is configured by subJsonPath.
|
|
id: return-subscription-as-a-json-array-of-proxy-configs-one-per-enabled-client-only-when-json-subscription-is-enabled-in-settings-the-path-prefix-is-configured-by-subjsonpath
|
|
- content: Return the JSON subscription status and metadata headers without a
|
|
body. Registered only when JSON subscriptions are enabled.
|
|
id: return-the-json-subscription-status-and-metadata-headers-without-a-body-registered-only-when-json-subscriptions-are-enabled
|
|
- content: Return subscription as a Clash/Mihomo-compatible YAML config, including
|
|
configured global Clash routing rules. Only when Clash subscription is
|
|
enabled in settings. The path prefix is configured by subClashPath.
|
|
id: return-subscription-as-a-clashmihomo-compatible-yaml-config-including-configured-global-clash-routing-rules-only-when-clash-subscription-is-enabled-in-settings-the-path-prefix-is-configured-by-subclashpath
|
|
- content: Return the Clash subscription status and metadata headers without a
|
|
body. Registered only when Clash subscriptions are enabled.
|
|
id: return-the-clash-subscription-status-and-metadata-headers-without-a-body-registered-only-when-clash-subscriptions-are-enabled
|
|
contents:
|
|
- content: 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.
|
|
heading: 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
|
|
---
|
|
|
|
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
|
|
|
export default function Layout(props) {
|
|
const { APIPage, OpenAPIPage } = props.components ?? {};
|
|
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
|
const Comp = OpenAPIPage ?? APIPage;
|
|
return (
|
|
<>
|
|
{props.children}
|
|
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/{subPath}{subid}","method":"get"},{"path":"/{subPath}{subid}","method":"head"},{"path":"/{subPath}{subid}/hwid-status","method":"get"},{"path":"/{subPath}{subid}/hwid-status","method":"head"},{"path":"/{jsonPath}{subid}","method":"get"},{"path":"/{jsonPath}{subid}","method":"head"},{"path":"/{clashPath}{subid}","method":"get"},{"path":"/{clashPath}{subid}","method":"head"}]} showTitle />
|
|
</>
|
|
);
|
|
} |