@aster-rpc/aster 0.1.2

package/dist/capabilities.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Capability requirement helpers for method-level access control.
+ *
+ * @example
+ * ```ts
+ * import { anyOf, allOf } from '@aster-rpc/aster';
+ *
+ * @Rpc({ requires: anyOf('ops.status', 'ops.admin') })
+ * async getStatus(req: StatusRequest): Promise<StatusResponse> { ... }
+ *
+ * @Rpc({ requires: allOf('ops.status', 'ops.admin') })
+ * async adminStatus(req: StatusRequest): Promise<StatusResponse> { ... }
+ * ```
+ */
+import type { CapabilityRequirement } from './service.js';
+/**
+ * Require ANY ONE of the listed roles (OR logic).
+ * The caller is admitted if they have at least one of the specified roles.
+ */
+export declare function anyOf(...roles: string[]): CapabilityRequirement;
+/**
+ * Require ALL of the listed roles (AND logic).
+ * The caller is admitted only if they have every specified role.
+ */
+export declare function allOf(...roles: string[]): CapabilityRequirement;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,qBAAqB,CAE/D;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,qBAAqB,CAE/D"}

package/dist/capabilities.js

@@ -0,0 +1,29 @@
+/**
+ * Capability requirement helpers for method-level access control.
+ *
+ * @example
+ * ```ts
+ * import { anyOf, allOf } from '@aster-rpc/aster';
+ *
+ * @Rpc({ requires: anyOf('ops.status', 'ops.admin') })
+ * async getStatus(req: StatusRequest): Promise<StatusResponse> { ... }
+ *
+ * @Rpc({ requires: allOf('ops.status', 'ops.admin') })
+ * async adminStatus(req: StatusRequest): Promise<StatusResponse> { ... }
+ * ```
+ */
+/**
+ * Require ANY ONE of the listed roles (OR logic).
+ * The caller is admitted if they have at least one of the specified roles.
+ */
+export function anyOf(...roles) {
+    return { kind: 'any_of', roles };
+}
+/**
+ * Require ALL of the listed roles (AND logic).
+ * The caller is admitted only if they have every specified role.
+ */
+export function allOf(...roles) {
+    return { kind: 'all_of', roles };
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,GAAG,KAAe;IACtC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,GAAG,KAAe;IACtC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACnC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Client stub generation.
+ *
+ * Creates a typed client proxy from a @Service-decorated class.
+ * Uses JavaScript Proxy for method interception with full TypeScript
+ * type inference — calling `client.echo(req)` has the correct types.
+ */
+import type { AsterTransport, CallOptions } from './transport/base.js';
+import { ServiceRegistry } from './service.js';
+/**
+ * Typed service client wrapper — provides service metadata accessors
+ * alongside the proxy methods. Returned by createClient().
+ */
+export declare class ServiceClient<T extends object> {
+    readonly proxy: AsterClient<T>;
+    private readonly _name;
+    private readonly _version;
+    constructor(serviceClass: new (...args: any[]) => T, transport: AsterTransport, options?: ClientOptions);
+    /** The RPC service name. */
+    get serviceName(): string;
+    /** The RPC service version. */
+    get serviceVersion(): number;
+}
+/** Options for creating a client. */
+export interface ClientOptions {
+    /** Default timeout in seconds for all calls. */
+    timeout?: number;
+    /** Default metadata for all calls. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Type helper: extracts the client interface from a service class.
+ *
+ * For each @Rpc method `foo(req: A): Promise<B>`, the client has
+ * `foo(req: A, opts?: CallOptions): Promise<B>`.
+ */
+export type AsterClient<T> = {
+    [K in keyof T as T[K] extends (...args: any[]) => any ? K : never]: T[K] extends (...args: infer A) => infer R ? (...args: [...A, opts?: CallOptions]) => R : never;
+} & {
+    /** Close the underlying transport. */
+    close(): Promise<void>;
+};
+/**
+ * Create a typed client from a @Service-decorated class.
+ *
+ * @example
+ * ```ts
+ * const client = createClient(EchoService, transport);
+ * const result = await client.echo(new EchoRequest({ message: "hi" }));
+ * ```
+ */
+/**
+ * Create a typed client backed by an in-process LocalTransport (for testing).
+ */
+export declare function createLocalClient<T extends new (...args: any[]) => any>(serviceClass: T, registry: ServiceRegistry, options?: ClientOptions): AsterClient<InstanceType<T>>;
+/**
+ * Sleep for a given number of seconds (convenience for timeout tests).
+ */
+export declare function timeSleep(seconds: number): Promise<void>;
+/**
+ * Build a CallOptions object with explicit timeout and metadata.
+ */
+export declare function timeouts(timeoutS: number, metadata?: Record<string, string>): CallOptions;
+export declare function createClient<T extends new (...args: any[]) => any>(serviceClass: T, transport: AsterTransport, options?: ClientOptions): AsterClient<InstanceType<T>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;GAGG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM;IACzC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,YAAY,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,aAAa;IAQvG,4BAA4B;IAC5B,IAAI,WAAW,IAAI,MAAM,CAAuB;IAEhD,+BAA+B;IAC/B,IAAI,cAAc,IAAI,MAAM,CAA0B;CACvD;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;KAC1B,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GAAG,CAAC,GAAG,KAAK,GAC/D,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GACtC,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,GAC1C,KAAK;CACZ,GAAG;IACF,sCAAsC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF;;;;;;;;GAQG;AACH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrE,YAAY,EAAE,CAAC,EACf,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAG9B;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAKzF;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAChE,YAAY,EAAE,CAAC,EACf,SAAS,EAAE,cAAc,EACzB,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CA+D9B"}

package/dist/client.js

@@ -0,0 +1,108 @@
+/**
+ * Client stub generation.
+ *
+ * Creates a typed client proxy from a @Service-decorated class.
+ * Uses JavaScript Proxy for method interception with full TypeScript
+ * type inference — calling `client.echo(req)` has the correct types.
+ */
+import { RpcPattern } from './types.js';
+import { RpcError, StatusCode } from './status.js';
+import { getServiceInfo } from './service.js';
+import { LocalTransport } from './transport/local.js';
+/**
+ * Typed service client wrapper — provides service metadata accessors
+ * alongside the proxy methods. Returned by createClient().
+ */
+export class ServiceClient {
+    proxy;
+    _name;
+    _version;
+    constructor(serviceClass, transport, options) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.proxy = createClient(serviceClass, transport, options);
+        const info = getServiceInfo(serviceClass);
+        this._name = info?.name ?? serviceClass.name;
+        this._version = info?.version ?? 1;
+    }
+    /** The RPC service name. */
+    get serviceName() { return this._name; }
+    /** The RPC service version. */
+    get serviceVersion() { return this._version; }
+}
+/**
+ * Create a typed client from a @Service-decorated class.
+ *
+ * @example
+ * ```ts
+ * const client = createClient(EchoService, transport);
+ * const result = await client.echo(new EchoRequest({ message: "hi" }));
+ * ```
+ */
+/**
+ * Create a typed client backed by an in-process LocalTransport (for testing).
+ */
+export function createLocalClient(serviceClass, registry, options) {
+    const transport = new LocalTransport(registry);
+    return createClient(serviceClass, transport, options);
+}
+/**
+ * Sleep for a given number of seconds (convenience for timeout tests).
+ */
+export async function timeSleep(seconds) {
+    return new Promise(resolve => setTimeout(resolve, seconds * 1000));
+}
+/**
+ * Build a CallOptions object with explicit timeout and metadata.
+ */
+export function timeouts(timeoutS, metadata) {
+    return {
+        deadlineEpochMs: Date.now() + timeoutS * 1000,
+        metadata,
+    };
+}
+export function createClient(serviceClass, transport, options) {
+    const serviceInfo = getServiceInfo(serviceClass);
+    if (!serviceInfo) {
+        throw new TypeError(`${serviceClass.name} is not decorated with @Service.`);
+    }
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (prop === 'close') {
+                return () => transport.close();
+            }
+            if (typeof prop !== 'string')
+                return undefined;
+            const methodInfo = serviceInfo.methods.get(prop);
+            if (!methodInfo)
+                return undefined;
+            return (...args) => {
+                // Last arg might be CallOptions
+                let request = args[0];
+                let callOpts;
+                if (args.length > 1 && typeof args[args.length - 1] === 'object') {
+                    callOpts = args[args.length - 1];
+                }
+                const opts = {
+                    ...callOpts,
+                    metadata: { ...options?.metadata, ...callOpts?.metadata },
+                };
+                if (options?.timeout && !opts.deadlineEpochMs) {
+                    opts.deadlineEpochMs = Date.now() + options.timeout * 1000;
+                }
+                switch (methodInfo.pattern) {
+                    case RpcPattern.UNARY:
+                        return transport.unary(serviceInfo.name, methodInfo.name, request, opts);
+                    case RpcPattern.SERVER_STREAM:
+                        return transport.serverStream(serviceInfo.name, methodInfo.name, request, opts);
+                    case RpcPattern.CLIENT_STREAM:
+                        return transport.clientStream(serviceInfo.name, methodInfo.name, request, opts);
+                    case RpcPattern.BIDI_STREAM:
+                        return transport.bidiStream(serviceInfo.name, methodInfo.name, opts);
+                    default:
+                        throw new RpcError(StatusCode.UNIMPLEMENTED, `Unknown pattern: ${methodInfo.pattern}`);
+                }
+            };
+        },
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/codec.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Codec abstraction — serialization + optional zstd compression.
+ *
+ * Spec reference: S5.1 (serialization), S5.2 (compression)
+ *
+ * Provides:
+ * - JsonCodec: JSON over UTF-8 bytes (testing, development)
+ * - ForyCodec: @apache-fory/core XLANG (production cross-language)
+ * - Zstd compression for payloads > threshold
+ */
+import { WIRE_TYPE_KEY } from './decorators.js';
+/** Default compression threshold in bytes (4 KiB). */
+export declare const DEFAULT_COMPRESSION_THRESHOLD = 4096;
+/** Re-export WIRE_TYPE_KEY as wireType for API compatibility. */
+export { WIRE_TYPE_KEY as wireType };
+/** Get the wire type tag from a @WireType-decorated class. */
+export declare function getWireType(cls: unknown): string | undefined;
+/** Generic codec interface for serialization/deserialization. */
+export interface Codec {
+    encode(obj: unknown, hintType?: unknown): Uint8Array;
+    decode(payload: Uint8Array, hintType?: unknown): unknown;
+    encodeCompressed(obj: unknown): [data: Uint8Array, compressed: boolean];
+    decodeCompressed(payload: Uint8Array, compressed: boolean, hintType?: unknown): unknown;
+}
+/**
+ * Simple JSON codec for cross-language interop and development.
+ *
+ * Strict mode: when ``decode`` is called with a ``hintType`` argument
+ * (a @WireType-decorated class constructor), the codec validates that
+ * every key in the decoded object matches a field declared on the
+ * class. Unknown keys raise ``ContractViolationError`` -- the producer
+ * owns the contract, and consumers must use the field names defined
+ * by the producer's manifest. Validation walks nested objects and
+ * arrays recursively, so a bad field at any depth fails loudly.
+ *
+ * If ``hintType`` is omitted (or is ``null``/``undefined``), decoding
+ * is permissive and returns the raw parsed value -- the codec doesn't
+ * know what shape to enforce. Callers that need strict validation
+ * must always pass the expected type.
+ */
+export declare class JsonCodec implements Codec {
+    private encoder;
+    private decoder;
+    private threshold;
+    constructor(compressionThreshold?: number);
+    encode(obj: unknown): Uint8Array;
+    decode(payload: Uint8Array, hintType?: unknown): unknown;
+    encodeCompressed(obj: unknown): [Uint8Array, boolean];
+    decodeCompressed(payload: Uint8Array, compressed: boolean, hintType?: unknown): unknown;
+}
+/**
+ * Walk the type graph starting from root types, discovering nested @WireType
+ * classes by inspecting default values of instances.
+ *
+ * Returns all discovered types in dependency order (leaves first), suitable
+ * for registration with Fory. This is the TS equivalent of Python's
+ * `_walk_type_graph()`.
+ *
+ * Limitations (compared to Python's dataclass introspection):
+ * - Only discovers nested types whose default values are instances of @WireType classes
+ * - Types in arrays, optionals, or maps that default to empty/null must be registered explicitly
+ *
+ * @param rootTypes - Classes decorated with @WireType
+ * @returns All types in dependency order (leaves first)
+ */
+export declare function walkTypeGraph(rootTypes: (new (...args: any[]) => any)[]): (new (...args: any[]) => any)[];
+/**
+ * Configuration for the Fory serializer.
+ */
+export declare class ForyConfig {
+    /** Compression threshold in bytes (default: 4096). */
+    compressionThreshold: number;
+    /** Whether to use cross-language mode (xlang). Default: true. */
+    xlang: boolean;
+    constructor(opts?: {
+        compressionThreshold?: number;
+        xlang?: boolean;
+    });
+    /** The resolved xlang mode (same as xlang field). */
+    get resolvedXlang(): boolean;
+    /** Convert to kwargs-style object for passing to Fory constructor. */
+    toKwargs(): Record<string, unknown>;
+}
+/** Resolved ForyConfig with all defaults filled in. */
+export interface ResolvedForyConfig {
+    compressionThreshold: number;
+    xlang: boolean;
+    /** Resolved xlang (same as xlang). */
+    resolvedXlang: boolean;
+}
+/**
+ * Resolve a ForyConfig with defaults.
+ */
+export declare function resolveForyConfig(config?: ForyConfig | {
+    compressionThreshold?: number;
+    xlang?: boolean;
+}): ResolvedForyConfig;
+/**
+ * ForyCodec — cross-language serialization via @apache-fory/core.
+ *
+ * Wraps the Fory JS XLANG serializer for wire-compatible serialization
+ * with Python's pyfory.
+ *
+ * @example
+ * ```ts
+ * import Fory from '@apache-fory/core';
+ * const fory = new Fory({ compatible: true });
+ * const codec = new ForyCodec(fory);
+ * ```
+ */
+export declare class ForyCodec implements Codec {
+    readonly fory: any;
+    private threshold;
+    private serializers;
+    constructor(foryInstance: any, compressionThreshold?: number);
+    /** Register a type for serialization. */
+    registerType(typeInfo: any): void;
+    /**
+     * Walk the type graph from root types and register all discovered
+     * @WireType classes with Fory. Types are registered in dependency
+     * order (leaves first).
+     *
+     * @param rootTypes - Classes decorated with @WireType
+     * @param buildTypeInfo - Function that converts a class to a Fory typeInfo object.
+     *   Receives (cls, wireTag) and should return the object to pass to registerType().
+     */
+    registerTypeGraph(rootTypes: (new (...args: any[]) => any)[], buildTypeInfo: (cls: new (...args: any[]) => any, wireTag: string) => any): void;
+    encode(obj: unknown, _hintType?: unknown): Uint8Array;
+    decode(payload: Uint8Array, _hintType?: unknown): unknown;
+    encodeCompressed(obj: unknown): [Uint8Array, boolean];
+    decodeCompressed(payload: Uint8Array, compressed: boolean, hintType?: unknown): unknown;
+    /**
+     * Compress bytes using zstd (if available).
+     * Returns null if zstd is unavailable or compression didn't help.
+     */
+    compress(data: Uint8Array): Uint8Array | null;
+    /**
+     * Decompress zstd-compressed bytes.
+     */
+    decompress(data: Uint8Array): Uint8Array;
+    /**
+     * Encode a row schema for a list of field names (for row-oriented data).
+     * Returns a JSON-encoded schema descriptor.
+     */
+    encodeRowSchema(fields: string[]): Uint8Array;
+    /**
+     * Decode a row-oriented data payload using a previously decoded schema.
+     * Reconstructs objects from parallel arrays.
+     */
+    decodeRowData(schemaBytes: Uint8Array, dataBytes: Uint8Array): unknown[];
+    /**
+     * Return the list of registered type names.
+     */
+    registeredTypes(): string[];
+}
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"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"}