@openclaw/diagnostics-otel 2026.7.2-beta.7 → 2026.7.34

package/node_modules/@opentelemetry/sdk-node/node_modules/@types/node/ffi.d.ts

@@ -0,0 +1,486 @@
+declare module "node:ffi" {
+    import { NonSharedBuffer } from "node:buffer";
+    interface FunctionSignature {
+        return?: ReturnType | undefined;
+        arguments?: readonly ArgumentType[] | undefined;
+    }
+    interface FunctionDefinitions {
+        [symbol: string]: FunctionSignature;
+    }
+    type CallbackFunction<R extends ReturnType = any, P extends readonly ArgumentType[] = any[]> = (
+        ...args: { [K in keyof P]: ArgumentTypeMap[DataTypeMap[P[K]]] }
+    ) => ReturnTypeMap[DataTypeMap[R]];
+    interface WrappedFunction<R extends ReturnType = any, P extends readonly ArgumentType[] = any[]>
+        extends CallbackFunction<R, P>
+    {
+        readonly pointer: bigint;
+    }
+    type CallbackFunctionFromSignature<T extends FunctionSignature> = CallbackFunction<
+        ReturnTypeFromFunctionSignature<T>,
+        ArgumentTypesFromFunctionSignature<T>
+    >;
+    type WrappedFunctionFromSignature<T extends FunctionSignature> = WrappedFunction<
+        ReturnTypeFromFunctionSignature<T>,
+        ArgumentTypesFromFunctionSignature<T>
+    >;
+    type WrappedFunctionsFromDefinitions<T extends FunctionDefinitions> = {
+        [K in keyof T]: WrappedFunctionFromSignature<T[K]>;
+    };
+    type ReturnTypeFromFunctionSignature<T extends FunctionSignature> = "return" extends keyof T
+        ? T extends { return: infer R extends ReturnType } ? R : any
+        : "void";
+    type ArgumentTypesFromFunctionSignature<T extends FunctionSignature> = "arguments" extends keyof T
+        ? T extends { arguments: infer P extends readonly ArgumentType[] } ? P : any[]
+        : [];
+    interface DynamicLibraryResult<T extends FunctionDefinitions> extends Disposable {
+        lib: DynamicLibrary;
+        functions: WrappedFunctionsFromDefinitions<T>;
+    }
+    /**
+     * The native shared library suffix for the current platform:
+     *
+     * * `'dylib'` on macOS
+     * * `'so'` on Unix-like platforms
+     * * `'dll'` on Windows
+     *
+     * This can be used to build portable library paths:
+     *
+     * ```js
+     * const { suffix } = require('node:ffi');
+     *
+     * const path = `libsqlite3.${suffix}`;
+     * ```
+     * @since v26.1.0
+     */
+    const suffix: string;
+    /**
+     * Loads a dynamic library and resolves the requested function definitions.
+     *
+     * On Windows passing `null` is not supported.
+     *
+     * When `definitions` is omitted, `functions` is returned as an empty object until
+     * symbols are resolved explicitly.
+     *
+     * The returned object also implements the explicit resource management protocol,
+     * so it can be used with the `using` declaration. Disposing the returned
+     * object closes the library handle.
+     *
+     * ```js
+     * import { dlopen } from 'node:ffi';
+     *
+     * {
+     *   using handle = dlopen('./mylib.so', {
+     *     add_i32: { arguments: ['i32', 'i32'], return: 'i32' },
+     *   });
+     *   console.log(handle.functions.add_i32(20, 22));
+     * } // handle.lib.close() is invoked automatically here.
+     * ```
+     *
+     * ```js
+     * import { dlopen } from 'node:ffi';
+     *
+     * const { lib, functions } = dlopen('./mylib.so', {
+     *   add_i32: { arguments: ['i32', 'i32'], return: 'i32' },
+     *   string_length: { arguments: ['pointer'], return: 'u64' },
+     * });
+     *
+     * console.log(functions.add_i32(20, 22));
+     * ```
+     * @since v26.1.0
+     * @param path Path to a dynamic library, or `null` to resolve symbols
+     * from the current process image.
+     * @param definitions Symbol definitions to resolve immediately.
+     */
+    function dlopen<const T extends FunctionDefinitions = {}>(
+        path: string | null,
+        definitions?: T,
+    ): DynamicLibraryResult<T>;
+    /**
+     * Closes a dynamic library.
+     *
+     * This is equivalent to calling `handle.close()`.
+     * @since v26.1.0
+     */
+    function dlclose(handle: DynamicLibrary): void;
+    /**
+     * Resolves a symbol address from a loaded library.
+     *
+     * This is equivalent to calling `handle.getSymbol(symbol)`.
+     * @since v26.1.0
+     */
+    function dlsym(handle: DynamicLibrary, symbol: string): bigint;
+    /**
+     * @since v26.1.0
+     */
+    class DynamicLibrary {
+        /**
+         * Loads the dynamic library without resolving any functions eagerly.
+         *
+         * On Windows passing `null` is not supported.
+         *
+         * ```js
+         * const { DynamicLibrary } = require('node:ffi');
+         *
+         * const lib = new DynamicLibrary('./mylib.so');
+         * ```
+         * @param path Path to a dynamic library, or `null` to resolve symbols
+         * from the current process image.
+         */
+        constructor(path: string | null);
+        /**
+         * The path used to load the library.
+         */
+        readonly path: string;
+        /**
+         * An object containing previously resolved symbol addresses as `bigint` values.
+         */
+        readonly symbols: { [symbol: string]: bigint };
+        /**
+         * Closes the library handle.
+         *
+         * `DynamicLibrary` implements the explicit resource management protocol, so a
+         * library instance can be managed with the `using` declaration. Leaving the
+         * enclosing scope invokes `library.close()` automatically.
+         *
+         * ```js
+         * import { DynamicLibrary } from 'node:ffi';
+         *
+         * {
+         *   using lib = new DynamicLibrary('./mylib.so');
+         *   // Use `lib` here; `lib.close()` is called when the block exits.
+         * }
+         * ```
+         *
+         * Calling `library.close()` (or disposing the library) more than once is a no-op.
+         *
+         * After a library has been closed:
+         *
+         * * Resolved function wrappers become invalid.
+         * * Further symbol and function resolution throws.
+         * * Registered callbacks are invalidated.
+         *
+         * Closing a library does not make previously exported callback pointers safe to
+         * reuse. Node.js does not track or revoke callback pointers that have already
+         * been handed to native code.
+         *
+         * If native code still holds a callback pointer after `library.close()` or after
+         * `library.unregisterCallback(pointer)`, invoking that pointer has undefined
+         * behavior, is not allowed, and is dangerous: it can crash the process, produce
+         * incorrect output, or corrupt memory. Native code must stop using callback
+         * addresses before the library is closed or before the callback is unregistered.
+         *
+         * Calling `library.close()` from one of the library's active callbacks is
+         * unsupported and dangerous. The callback must return before the library is
+         * closed.
+         */
+        close(): void;
+        /**
+         * Calls `library.close()`. This allows `DynamicLibrary` instances to be used with
+         * the `using` declaration for automatic cleanup when the enclosing scope
+         * exits. It is a no-op on a library that has already been closed.
+         * @since v26.1.0
+         */
+        [Symbol.dispose](): void;
+        /**
+         * Resolves a symbol and returns a callable JavaScript wrapper.
+         *
+         * The returned function has a `.pointer` property containing the native function
+         * address as a `bigint`.
+         *
+         * If the same symbol has already been resolved, requesting it again with a
+         * different signature throws.
+         *
+         * ```js
+         * const { DynamicLibrary } = require('node:ffi');
+         *
+         * const lib = new DynamicLibrary('./mylib.so');
+         * const add = lib.getFunction('add_i32', {
+         *   arguments: ['i32', 'i32'],
+         *   return: 'i32',
+         * });
+         *
+         * console.log(add(20, 22));
+         * console.log(add.pointer);
+         * ```
+         */
+        getFunction<const T extends FunctionSignature>(name: string, signature: T): WrappedFunctionFromSignature<T>;
+        /**
+         * When `definitions` is provided, resolves each named symbol and returns an
+         * object containing callable wrappers.
+         *
+         * When `definitions` is omitted, returns wrappers for all functions that have
+         * already been resolved on the library.
+         */
+        getFunctions(): { [symbol: string]: WrappedFunction };
+        getFunctions<const T extends FunctionDefinitions>(definitions: T): WrappedFunctionsFromDefinitions<T>;
+        /**
+         * Resolves a symbol and returns its native address as a `bigint`.
+         */
+        getSymbol(name: string): bigint;
+        /**
+         * Returns an object containing all previously resolved symbol addresses.
+         */
+        getSymbols(): Record<string, bigint>;
+        /**
+         * Creates a native callback pointer backed by a JavaScript function.
+         *
+         * When `signature` is omitted, the callback uses a default `void ()` signature.
+         *
+         * The return value is the callback pointer address as a `bigint`. It can be
+         * passed to native functions expecting a callback pointer.
+         *
+         * ```js
+         * const { DynamicLibrary } = require('node:ffi');
+         *
+         * const lib = new DynamicLibrary('./mylib.so');
+         *
+         * const callback = lib.registerCallback(
+         *   { arguments: ['i32'], return: 'i32' },
+         *   (value) => value * 2,
+         * );
+         * ```
+         *
+         * Callbacks are subject to the following restrictions:
+         *
+         * * They must be invoked on the same system thread where they were created.
+         * * They must not throw exceptions.
+         * * They must not return promises.
+         * * They must return a value compatible with the declared return type.
+         * * They must not call `library.close()` on their owning library while running.
+         * * They must not unregister themselves while running.
+         *
+         * Closing the owning library or unregistering the currently executing callback
+         * from inside the callback is unsupported and dangerous. Doing so may crash the
+         * process, produce incorrect output, or corrupt memory.
+         */
+        registerCallback(callback: () => void): bigint;
+        registerCallback<const T extends FunctionSignature>(
+            signature: T,
+            callback: CallbackFunctionFromSignature<T>,
+        ): bigint;
+        /**
+         * Releases a callback previously created with `library.registerCallback()`.
+         *
+         * Calling `library.unregisterCallback(pointer)` for a callback that is currently
+         * executing is unsupported and dangerous. The callback must return before it is
+         * unregistered.
+         *
+         * After `library.unregisterCallback(pointer)` returns, invoking that callback
+         * pointer from native code has undefined behavior, is not allowed, and is
+         * dangerous: it can crash the process, produce incorrect output, or corrupt
+         * memory.
+         */
+        unregisterCallback(pointer: bigint): void;
+        /**
+         * Keeps the callback strongly referenced by JavaScript.
+         */
+        refCallback(pointer: bigint): void;
+        /**
+         * Allows the callback to become weakly referenced by JavaScript.
+         *
+         * If the callback function is later garbage collected, subsequent native
+         * invocations become a no-op. Non-void return values are zero-initialized before
+         * returning to native code.
+         */
+        unrefCallback(pointer: bigint): void;
+    }
+    function getInt8(pointer: bigint, offset?: number): number;
+    function getUint8(pointer: bigint, offset?: number): number;
+    function getInt16(pointer: bigint, offset?: number): number;
+    function getUint16(pointer: bigint, offset?: number): number;
+    function getInt32(pointer: bigint, offset?: number): number;
+    function getUint32(pointer: bigint, offset?: number): number;
+    function getInt64(pointer: bigint, offset?: number): bigint;
+    function getUint64(pointer: bigint, offset?: number): bigint;
+    function getFloat32(pointer: bigint, offset?: number): number;
+    function getFloat64(pointer: bigint, offset?: number): number;
+    function setInt8(pointer: bigint, offset: number, value: number): void;
+    function setUint8(pointer: bigint, offset: number, value: number): void;
+    function setInt16(pointer: bigint, offset: number, value: number): void;
+    function setUint16(pointer: bigint, offset: number, value: number): void;
+    function setInt32(pointer: bigint, offset: number, value: number): void;
+    function setUint32(pointer: bigint, offset: number, value: number): void;
+    function setInt64(pointer: bigint, offset: number, value: number | bigint): void;
+    function setUint64(pointer: bigint, offset: number, value: number | bigint): void;
+    function setFloat32(pointer: bigint, offset: number, value: number): void;
+    function setFloat64(pointer: bigint, offset: number, value: number): void;
+    /**
+     * Reads a NUL-terminated UTF-8 string from native memory.
+     *
+     * If `pointer` is `0n`, `null` is returned.
+     *
+     * This function does not validate that `pointer` refers to readable memory or
+     * that the pointed-to data is terminated with `\0`. Passing an invalid pointer,
+     * a pointer to freed memory, or a pointer to bytes without a terminating NUL can
+     * read unrelated memory, crash the process, or produce truncated or garbled
+     * output.
+     * @since v26.1.0
+     */
+    function toString(pointer: bigint): string | null;
+    /**
+     * Creates a `Buffer` from native memory.
+     *
+     * When `copy` is `true`, the returned `Buffer` owns its own copied memory.
+     * When `copy` is `false`, the returned `Buffer` references the original native
+     * memory directly.
+     *
+     * Using `copy: false` is a zero-copy escape hatch. The returned `Buffer` is a
+     * writable view onto foreign memory, so writes in JavaScript update the original
+     * native memory directly. The caller must guarantee that:
+     *
+     * * `pointer` remains valid for the entire lifetime of the returned `Buffer`.
+     * * `length` stays within the allocated native region.
+     * * no native code frees or repurposes that memory while JavaScript still uses
+     *   the `Buffer`.
+     * * Memory protection is observed. For example, read-only memory pages must not
+     *   be written to.
+     *
+     * If these guarantees are not met, reading or writing the `Buffer` can corrupt
+     * memory or crash the process.
+     * @since v26.1.0
+     * @param copy When `false`, creates a zero-copy view. **Default:** `true`.
+     */
+    function toBuffer(pointer: bigint, length: number, copy?: boolean): NonSharedBuffer;
+    /**
+     * Creates an `ArrayBuffer` from native memory.
+     *
+     * When `copy` is `true`, the returned `ArrayBuffer` contains copied bytes.
+     * When `copy` is `false`, the returned `ArrayBuffer` references the original
+     * native memory directly.
+     *
+     * The same lifetime and bounds requirements described for
+     * `ffi.toBuffer(pointer, length, copy)` apply
+     * here. With `copy: false`, the
+     * returned `ArrayBuffer` is a zero-copy view of foreign memory and is only safe
+     * while that memory remains allocated, unchanged in layout, and valid for the
+     * entire exposed range.
+     * @since v26.1.0
+     * @param copy When `false`, creates a zero-copy view. **Default:** `true`.
+     */
+    function toArrayBuffer(pointer: bigint, length: number, copy?: boolean): ArrayBuffer;
+    /**
+     * Copies a JavaScript string into native memory and appends a trailing NUL
+     * terminator.
+     *
+     * `length` must be large enough to hold the full encoded string plus the trailing
+     * NUL terminator. For UTF-16 and UCS-2 encodings, the trailing terminator uses
+     * two zero bytes.
+     *
+     * `pointer` must refer to writable native memory with at least `length` bytes of
+     * available storage. This function does not allocate memory on its own.
+     *
+     * `string` must be a JavaScript string. `encoding` must be a string.
+     * @since v26.1.0
+     * @param encoding **Default:** `'utf8'`.
+     */
+    function exportString(string: string, pointer: bigint, length: number, encoding?: BufferEncoding): void;
+    /**
+     * Copies bytes from a `Buffer` into native memory.
+     *
+     * `length` must be at least `buffer.length`.
+     *
+     * `pointer` must refer to writable native memory with at least `length` bytes of
+     * available storage. This function does not allocate memory on its own.
+     *
+     * `buffer` must be a Node.js `Buffer`.
+     * @since v26.1.0
+     */
+    function exportBuffer(buffer: Buffer, pointer: bigint, length: number): void;
+    /**
+     * Copies bytes from an `ArrayBuffer` into native memory.
+     *
+     * `length` must be at least `arrayBuffer.byteLength`.
+     *
+     * `pointer` must refer to writable native memory with at least `length` bytes of
+     * available storage. This function does not allocate memory on its own.
+     * @since v26.1.0
+     */
+    function exportArrayBuffer(arrayBuffer: ArrayBuffer, pointer: bigint, length: number): void;
+    /**
+     * Copies bytes from an `ArrayBufferView` into native memory.
+     *
+     * `length` must be at least `arrayBufferView.byteLength`.
+     *
+     * `pointer` must refer to writable native memory with at least `length` bytes of
+     * available storage. This function does not allocate memory on its own.
+     * @since v26.1.0
+     */
+    function exportArrayBufferView(arrayBufferView: NodeJS.ArrayBufferView, pointer: bigint, length: number): void;
+    /**
+     * Returns the raw memory address of JavaScript-managed byte storage.
+     *
+     * This is unsafe and dangerous. The returned pointer can become invalid if the
+     * underlying memory is detached, resized, transferred, or otherwise invalidated.
+     * Using stale pointers can cause memory corruption or process crashes.
+     * @since v26.1.0
+     */
+    function getRawPointer(source: ArrayBuffer | NodeJS.ArrayBufferView): bigint;
+    type ReturnType = { [K in keyof DataTypeMap]: K }[keyof DataTypeMap];
+    type ArgumentType = Exclude<ReturnType, "void">;
+    interface DataTypeMap {
+        void: "void";
+        char: "number";
+        bool: "number";
+        i8: "number";
+        int8: "number";
+        u8: "number";
+        uint8: "number";
+        i16: "number";
+        int16: "number";
+        u16: "number";
+        uint16: "number";
+        i32: "number";
+        int32: "number";
+        u32: "number";
+        uint32: "number";
+        i64: "bigint";
+        int64: "bigint";
+        u64: "bigint";
+        uint64: "bigint";
+        float: "number";
+        f32: "number";
+        double: "number";
+        f64: "number";
+        pointer: "pointer";
+        ptr: "pointer";
+        function: "pointer";
+        buffer: "pointer";
+        arraybuffer: "pointer";
+        string: "pointer";
+        str: "pointer";
+    }
+    interface ArgumentTypeMap {
+        "number": number;
+        "bigint": bigint;
+        "pointer": bigint | string | ArrayBuffer | NodeJS.ArrayBufferView | null;
+    }
+    interface ReturnTypeMap {
+        // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+        "void": void;
+        "number": number;
+        "bigint": bigint;
+        "pointer": bigint | null;
+    }
+    enum types {
+        VOID = "void",
+        POINTER = "pointer",
+        BUFFER = "buffer",
+        ARRAY_BUFFER = "arraybuffer",
+        FUNCTION = "function",
+        BOOL = "bool",
+        CHAR = "char",
+        STRING = "string",
+        FLOAT = "float",
+        DOUBLE = "double",
+        INT_8 = "int8",
+        UINT_8 = "uint8",
+        INT_16 = "int16",
+        UINT_16 = "uint16",
+        INT_32 = "int32",
+        UINT_32 = "uint32",
+        INT_64 = "int64",
+        UINT_64 = "uint64",
+        FLOAT_32 = "float32",
+        FLOAT_64 = "float64",
+    }
+}