@kissesses/xtls-sdk 0.16.0

package/build/src/stats/stats.service.js

@@ -0,0 +1,527 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatsService = void 0;
+const nice_grpc_1 = require("nice-grpc");
+const models_1 = require("./models");
+const command_1 = require("../xray-protos/app/stats/command/command");
+const errors_1 = require("../common/errors");
+/**
+ * Service class for interacting with Xray server statistics.
+ * Provides methods to retrieve system and user statistics.
+ *
+ * @example
+ * ```typescript
+ * // Create a new StatsService instance
+ * const stats = new StatsService(channel);
+ *
+ * // Get system stats
+ * const sysStats = await stats.getSysStats();
+ *
+ * // Get all users stats
+ * const allUsersStats = await stats.getAllUsersStats();
+ *
+ * // Get specific user stats
+ * const userStats = await stats.getUserStats('username123');
+ *
+ * // Check if user is online
+ * const isOnline = await stats.getUserOnlineStatus('username123');
+ * ```
+ */
+class StatsService {
+    /**
+     * Creates a new StatsService instance
+     * @param channel - The gRPC channel to use for communication with the Xray server
+     */
+    constructor(channel) {
+        this.channel = channel;
+        /**
+         * Cached flag indicating whether the remote Xray server supports the
+         * `GetUsersStats` unary method. `null` means "not probed yet", `true` means
+         * the method is available, `false` means the legacy fallback should be used.
+         *
+         * The flag is cached for the lifetime of this instance — if the Xray core
+         * is upgraded without re-creating the SDK, a manual re-instantiation is
+         * required to re-detect support.
+         * @private
+         */
+        this.supportsGetUsersStats = null;
+        this.client = (0, nice_grpc_1.createClient)(command_1.StatsServiceDefinition, channel);
+    }
+    /**
+     * Retrieves system statistics from the Xray server.
+     * This includes information about the system's overall performance and resource usage.
+     *
+     * @returns {Promise<ISdkResponse<GetSysStatsResponseModel>>} A promise that resolves to:
+     * - On success: An object with `isOk: true` and `data` containing the system stats
+     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
+     *
+     * @example
+     * ```typescript
+     * const stats = new StatsService(channel);
+     * const response = await stats.getSysStats();
+     *
+     * if (response.isOk) {
+     *   console.log(response.data); // GetSysStatsResponseModel
+     * } else {
+     *   console.error(response.message); // Error message
+     * }
+     * ```
+     */
+    async getSysStats() {
+        try {
+            const response = await this.client.getSysStats({});
+            return {
+                isOk: true,
+                data: new models_1.GetSysStatsResponseModel(response),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_SYS_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Retrieves statistics for all users from the Xray server.
+     * This provides a comprehensive view of all user activities and their resource usage.
+     *
+     * @param {boolean} reset - Whether to reset the statistics after retrieving them. Defaults to false.
+     * @returns {Promise<ISdkResponse<GetAllUsersStatsResponseModel>>} A promise that resolves to:
+     * - On success: An object with `isOk: true` and `data` containing user stats
+     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
+     *
+     * @example
+     * ```typescript
+     * const stats = new StatsService(channel);
+     *
+     * // Get stats without resetting
+     * const response = await stats.getAllUsersStats();
+     *
+     * // Get stats and reset them
+     * const responseWithReset = await stats.getAllUsersStats(true);
+     *
+     * if (response.isOk) {
+     *   console.log(response.data.users); // Array of user statistics
+     * } else {
+     *   console.error(response.message); // Error message
+     * }
+     * ```
+     */
+    async getAllUsersStats(reset = false) {
+        try {
+            const response = await this.client.queryStats({
+                pattern: 'user>>>',
+                reset,
+            });
+            return {
+                isOk: true,
+                data: new models_1.GetAllUsersStatsResponseModel(response),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_ALL_USERS_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Retrieves statistics for a specific user from the Xray server.
+     * This includes detailed information about the user's network usage, connections, and other metrics.
+     *
+     * @param {string} username - The username to get statistics for
+     * @param {boolean} reset - Whether to reset the statistics after retrieving them. Defaults to false.
+     * @returns {Promise<ISdkResponse<GetUserStatsResponseModel>>} A promise that resolves to:
+     * - On success: An object with `isOk: true` and `data` containing the user's stats
+     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
+     *
+     * @example
+     * ```typescript
+     * const stats = new StatsService(channel);
+     *
+     * // Get user stats without resetting
+     * const response = await stats.getUserStats('username123');
+     *
+     * // Get user stats and reset them
+     * const responseWithReset = await stats.getUserStats('username123', true);
+     *
+     * if (response.isOk) {
+     *   console.log(response.data.user); // User statistics
+     * } else {
+     *   console.error(response.message); // Error message
+     * }
+     * ```
+     */
+    async getUserStats(username, reset = false) {
+        try {
+            const response = await this.client.queryStats({
+                pattern: `user>>>${username}>>>`,
+                reset,
+            });
+            return {
+                isOk: true,
+                data: new models_1.GetUserStatsResponseModel(response),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_USER_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Checks if a specific user is currently online on the Xray server.
+     * This method queries the server's real-time connection status for the specified user.
+     *
+     * @param {string} username - The username to check online status for
+     * @returns {Promise<ISdkResponse<GetUserOnlineStatusResponseModel>>} A promise that resolves to:
+     * - On success: An object with `isOk: true` and `data` containing the user's online status (`data.online`)
+     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
+     *
+     * @example
+     * ```typescript
+     * const stats = new StatsService(channel);
+     * const response = await stats.getUserOnlineStatus('username123');
+     *
+     * if (response.isOk) {
+     *   if (response.data.online) {
+     *     console.log('User is online');
+     *   } else {
+     *     console.log('User is offline');
+     *   }
+     * } else {
+     *   console.error(response.message); // Error message
+     * }
+     * ```
+     */
+    async getUserOnlineStatus(username) {
+        try {
+            await this.client.getStatsOnline({
+                name: `user>>>${username}>>>online`,
+            });
+            return {
+                isOk: true,
+                data: new models_1.GetUserOnlineStatusResponseModel(true),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            const isNotFound = message.includes('online not found.');
+            if (isNotFound) {
+                return {
+                    isOk: true,
+                    data: new models_1.GetUserOnlineStatusResponseModel(false),
+                };
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_USER_ONLINE_STATUS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Gets statistics for all inbound connections.
+     *
+     * @param reset - Whether to reset the statistics after retrieving them. Defaults to false.
+     * @returns A promise that resolves to an ISdkResponse containing:
+     * - On success: An object with `isOk: true` and data containing an array of inbound stats
+     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
+     *
+     * @example
+     * ```typescript
+     * const stats = new StatsService(channel);
+     * const response = await stats.getAllInboundsStats();
+     *
+     * if (response.isOk) {
+     *   console.log('Inbound stats:', response.data.inbounds);
+     * } else {
+     *   console.error(response.message); // Error message
+     * }
+     * ```
+     */
+    async getAllInboundsStats(reset = false) {
+        try {
+            const response = await this.client.queryStats({
+                pattern: 'inbound>>>',
+                reset,
+            });
+            return {
+                isOk: true,
+                data: new models_1.GetAllInboundsStatsResponseModel(response),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_ALL_INBOUNDS_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Gets statistics for a specific inbound connection.
+     *
+     * @param inbound - The name/tag of the inbound connection to get stats for
+     * @param reset - Whether to reset the statistics after retrieving them. Defaults to false.
+     * @returns A promise that resolves to an ISdkResponse containing:
+     * - On success: An object with `isOk: true` and data containing the inbound stats
+     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
+     *
+     * @example
+     * ```typescript
+     * const stats = new StatsService(channel);
+     * const response = await stats.getInboundStats('http_in');
+     *
+     * if (response.isOk) {
+     *   console.log('Inbound stats:', response.data.stats);
+     * } else {
+     *   console.error(response.message); // Error message
+     * }
+     * ```
+     */
+    async getInboundStats(inbound, reset = false) {
+        try {
+            const response = await this.client.queryStats({
+                pattern: `inbound>>>${inbound}>>>`,
+                reset,
+            });
+            return {
+                isOk: true,
+                data: new models_1.GetInboundStatsResponseModel(response),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_INBOUND_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Gets statistics for all outbound connections.
+     *
+     * @param reset - Whether to reset the statistics after retrieving them. Defaults to false.
+     * @returns A promise that resolves to an ISdkResponse containing:
+     * - On success: An object with `isOk: true` and data containing an array of outbound stats
+     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
+     *
+     * @example
+     * ```typescript
+     * const stats = new StatsService(channel);
+     * const response = await stats.getAllOutboundsStats();
+     *
+     * if (response.isOk) {
+     *   console.log('Outbound stats:', response.data.outbounds);
+     * } else {
+     *   console.error(response.message); // Error message
+     * }
+     * ```
+     */
+    async getAllOutboundsStats(reset = false) {
+        try {
+            const response = await this.client.queryStats({
+                pattern: 'outbound>>>',
+                reset,
+            });
+            return {
+                isOk: true,
+                data: new models_1.GetAllOutboundsStatsResponseModel(response),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_ALL_OUTBOUNDS_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Gets statistics for a specific outbound connection.
+     *
+     * @param outbound - The name/tag of the outbound connection to get stats for
+     * @param reset - Whether to reset the statistics after retrieving them. Defaults to false.
+     * @returns A promise that resolves to an ISdkResponse containing:
+     * - On success: An object with `isOk: true` and data containing the outbound stats
+     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
+     *
+     * @example
+     * ```typescript
+     * const stats = new StatsService(channel);
+     * const response = await stats.getOutboundStats('http_out');
+     *
+     * if (response.isOk) {
+     *   console.log('Outbound stats:', response.data.stats);
+     * } else {
+     *   console.error(response.message); // Error message
+     * }
+     * ```
+     */
+    async getOutboundStats(outbound, reset = false) {
+        try {
+            const response = await this.client.queryStats({
+                pattern: `outbound>>>${outbound}>>>`,
+                reset,
+            });
+            return {
+                isOk: true,
+                data: new models_1.GetOutboundStatsResponseModel(response),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_OUTBOUND_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Retrieves per-user statistics (online IP list and, optionally, traffic)
+     * from the Xray server.
+     *
+     * Prefers the native `GetUsersStats` gRPC method introduced in recent
+     * Xray-core versions. If the server replies with `UNIMPLEMENTED` (i.e. the
+     * method is missing), transparently falls back to the legacy approach of
+     * combining `GetAllOnlineUsers` + `GetStatsOnlineIpList`. The detection
+     * result is cached for the lifetime of this service instance, so the
+     * `UNIMPLEMENTED` round-trip happens at most once.
+     *
+     * Note: the `includeTraffic` flag is honored only on the native path. In
+     * legacy mode traffic is always returned as `undefined`, since the old
+     * endpoints do not expose per-user traffic in a single call.
+     *
+     * @param includeTraffic - Whether to request traffic counters alongside IPs (native path only).
+     * @param reset - Whether to reset the stats after retrieving them.
+     */
+    async getUsersStats(includeTraffic = false, reset = false) {
+        if (this.supportsGetUsersStats === false) {
+            return this.getUsersStatsLegacy(reset);
+        }
+        try {
+            const response = await this.client.getUsersStats({
+                includeTraffic,
+                reset,
+            });
+            this.supportsGetUsersStats = true;
+            return {
+                isOk: true,
+                data: new models_1.GetUsersStatsResponseModel(response),
+            };
+        }
+        catch (error) {
+            if (error instanceof nice_grpc_1.ClientError && error.code === nice_grpc_1.Status.UNIMPLEMENTED) {
+                this.supportsGetUsersStats = false;
+                return this.getUsersStatsLegacy(reset);
+            }
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_USERS_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Legacy fallback for {@link getUsersStats}. Uses `GetAllOnlineUsers` to
+     * enumerate currently connected users and then queries
+     * `GetStatsOnlineIpList` for each of them in parallel with a bounded
+     * worker pool. Always returns `traffic: undefined` for every user.
+     * @private
+     */
+    async getUsersStatsLegacy(reset) {
+        try {
+            const { users: onlineUsers } = await this.client.getAllOnlineUsers({});
+            const onlinePairs = Array.from(new Set(onlineUsers)).map((metricName) => ({
+                metricName,
+                email: metricName.slice('user>>>'.length, -'>>>online'.length),
+            }));
+            const results = new Array(onlinePairs.length);
+            const concurrency = Math.min(50, onlinePairs.length);
+            let cursor = 0;
+            const worker = async () => {
+                while (true) {
+                    const index = cursor++;
+                    if (index >= onlinePairs.length)
+                        return;
+                    const { metricName, email } = onlinePairs[index];
+                    let ips = [];
+                    try {
+                        const ipListResponse = await this.client.getStatsOnlineIpList({
+                            name: metricName,
+                            reset,
+                        });
+                        ips = Object.entries(ipListResponse.ips).map(([ip, lastSeen]) => ({
+                            ip,
+                            lastSeen: new Date(lastSeen * 1000),
+                        }));
+                    }
+                    catch {
+                        // ignore
+                    }
+                    results[index] = { userId: email, ips, traffic: undefined };
+                }
+            };
+            const workers = [];
+            for (let i = 0; i < concurrency; i++) {
+                workers.push(worker());
+            }
+            await Promise.all(workers);
+            const filtered = results.filter((user) => user.ips.length > 0);
+            return {
+                isOk: true,
+                data: models_1.GetUsersStatsResponseModel.fromUserStats(filtered),
+            };
+        }
+        catch (error) {
+            let message = '';
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            return {
+                isOk: false,
+                ...errors_1.STATS_ERRORS.GET_USERS_STATS_ERROR(message),
+            };
+        }
+    }
+    /**
+     * Gets the raw gRPC client for direct access to all stats service methods
+     * @returns The underlying StatsServiceClient instance
+     */
+    get rawClient() {
+        return this.client;
+    }
+}
+exports.StatsService = StatsService;

package/build/src/xray-protos/app/commander/config.d.ts

@@ -0,0 +1,37 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+import { TypedMessage } from "../../common/serial/typed_message";
+export declare const protobufPackage = "xray.app.commander";
+/** Config is the settings for Commander. */
+export interface Config {
+    $type: "xray.app.commander.Config";
+    /** Tag of the outbound handler that handles grpc connections. */
+    tag: string;
+    /** Network address of commander grpc service. */
+    listen: string;
+    /**
+     * Services that supported by this server. All services must implement Service
+     * interface.
+     */
+    service: TypedMessage[];
+}
+/** ReflectionConfig is the placeholder config for ReflectionService. */
+export interface ReflectionConfig {
+    $type: "xray.app.commander.ReflectionConfig";
+}
+export declare const Config: MessageFns<Config, "xray.app.commander.Config">;
+export declare const ReflectionConfig: MessageFns<ReflectionConfig, "xray.app.commander.ReflectionConfig">;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in Exclude<keyof T, "$type">]?: DeepPartial<T[K]>;
+} : Partial<T>;
+export interface MessageFns<T, V extends string> {
+    readonly $type: V;
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create(base?: DeepPartial<T>): T;
+    fromPartial(object: DeepPartial<T>): T;
+}
+export {};
+//# sourceMappingURL=config.d.ts.map

package/build/src/xray-protos/app/commander/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../../src/xray-protos/app/commander/config.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAGjE,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD,4CAA4C;AAC5C,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,2BAA2B,CAAC;IACnC,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,qCAAqC,CAAC;CAC9C;AAMD,eAAO,MAAM,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,2BAA2B,CA2FlE,CAAC;AAQF,eAAO,MAAM,gBAAgB,EAAE,UAAU,CAAC,gBAAgB,EAAE,qCAAqC,CAuChG,CAAC;AAIF,KAAK,OAAO,GAAG,IAAI,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEpF,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,GAAG,CAAC,GAC9C,CAAC,SAAS,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GACtE,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAChE,CAAC,SAAS,EAAE,GAAG;KAAG,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACvE,OAAO,CAAC,CAAC,CAAC,CAAC;AAMf,MAAM,WAAW,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM;IAC7C,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC;IACxD,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;IACzB,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC;IAC5B,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACjC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CACxC"}