mirror of
https://github.com/denoland/deno.git
synced 2024-11-23 15:16:54 -05:00
11b1e901ad
Adds support for passing and returning structs as buffers to FFI. This does not implement fastapi support for structs. Needed for certain system APIs such as AppKit on macOS.
1820 lines
56 KiB
TypeScript
1820 lines
56 KiB
TypeScript
// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
|
||
|
||
/// <reference no-default-lib="true" />
|
||
/// <reference lib="deno.ns" />
|
||
|
||
declare namespace Deno {
|
||
export {}; // stop default export type behavior
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Retrieve the process umask. If `mask` is provided, sets the process umask.
|
||
* This call always returns what the umask was before the call.
|
||
*
|
||
* ```ts
|
||
* console.log(Deno.umask()); // e.g. 18 (0o022)
|
||
* const prevUmaskValue = Deno.umask(0o077); // e.g. 18 (0o022)
|
||
* console.log(Deno.umask()); // e.g. 63 (0o077)
|
||
* ```
|
||
*
|
||
* This API is under consideration to determine if permissions are required to
|
||
* call it.
|
||
*
|
||
* *Note*: This API is not implemented on Windows
|
||
*
|
||
* @category File System
|
||
*/
|
||
export function umask(mask?: number): number;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* All plain number types for interfacing with foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type NativeNumberType =
|
||
| "u8"
|
||
| "i8"
|
||
| "u16"
|
||
| "i16"
|
||
| "u32"
|
||
| "i32"
|
||
| "f32"
|
||
| "f64";
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* All BigInt number types for interfacing with foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type NativeBigIntType =
|
||
| "u64"
|
||
| "i64"
|
||
| "usize"
|
||
| "isize";
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The native boolean type for interfacing to foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type NativeBooleanType = "bool";
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The native pointer type for interfacing to foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type NativePointerType = "pointer";
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The native buffer type for interfacing to foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type NativeBufferType = "buffer";
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The native function type for interfacing with foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type NativeFunctionType = "function";
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The native void type for interfacing with foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type NativeVoidType = "void";
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The native struct type for interfacing with foreign functions.
|
||
*
|
||
*/
|
||
type NativeStructType = { readonly struct: readonly NativeType[] };
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* All supported types for interfacing with foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export type NativeType =
|
||
| NativeNumberType
|
||
| NativeBigIntType
|
||
| NativeBooleanType
|
||
| NativePointerType
|
||
| NativeBufferType
|
||
| NativeFunctionType
|
||
| NativeStructType;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export type NativeResultType = NativeType | NativeVoidType;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A utility type conversion for foreign symbol parameters and unsafe callback
|
||
* return types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeTypeMap =
|
||
& Record<NativeNumberType, number>
|
||
& Record<NativeBigIntType, PointerValue>
|
||
& Record<NativeBooleanType, boolean>
|
||
& Record<NativePointerType, PointerValue | null>
|
||
& Record<NativeFunctionType, PointerValue | null>
|
||
& Record<NativeBufferType, BufferSource | null>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Type conversion for foreign symbol parameters and unsafe callback return
|
||
* types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeType<T extends NativeType = NativeType> = T extends
|
||
NativeStructType ? BufferSource
|
||
: ToNativeTypeMap[Exclude<T, NativeStructType>];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A utility type for conversion for unsafe callback return types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeResultTypeMap = ToNativeTypeMap & Record<NativeVoidType, void>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Type conversion for unsafe callback return types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeResultType<T extends NativeResultType = NativeResultType> =
|
||
T extends NativeStructType ? BufferSource
|
||
: ToNativeResultTypeMap[Exclude<T, NativeStructType>];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A utility type for conversion of parameter types of foreign functions.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeParameterTypes<T extends readonly NativeType[]> =
|
||
//
|
||
[(T[number])[]] extends [T] ? ToNativeType<T[number]>[]
|
||
: [readonly (T[number])[]] extends [T]
|
||
? readonly ToNativeType<T[number]>[]
|
||
: T extends readonly [...NativeType[]] ? {
|
||
[K in keyof T]: ToNativeType<T[K]>;
|
||
}
|
||
: never;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A utility type for conversion of foreign symbol return types and unsafe
|
||
* callback parameters.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeTypeMap =
|
||
& Record<NativeNumberType, number>
|
||
& Record<NativeBigIntType, PointerValue>
|
||
& Record<NativeBooleanType, boolean>
|
||
& Record<NativePointerType, PointerValue>
|
||
& Record<NativeBufferType, PointerValue>
|
||
& Record<NativeFunctionType, PointerValue>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Type conversion for foreign symbol return types and unsafe callback
|
||
* parameters.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeType<T extends NativeType = NativeType> = T extends
|
||
NativeStructType ? Uint8Array
|
||
: FromNativeTypeMap[Exclude<T, NativeStructType>];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A utility type for conversion for foreign symbol return types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeResultTypeMap =
|
||
& FromNativeTypeMap
|
||
& Record<NativeVoidType, void>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Type conversion for foreign symbol return types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeResultType<T extends NativeResultType = NativeResultType> =
|
||
T extends NativeStructType ? Uint8Array
|
||
: FromNativeResultTypeMap[Exclude<T, NativeStructType>];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeParameterTypes<
|
||
T extends readonly NativeType[],
|
||
> =
|
||
//
|
||
[(T[number])[]] extends [T] ? FromNativeType<T[number]>[]
|
||
: [readonly (T[number])[]] extends [T]
|
||
? readonly FromNativeType<T[number]>[]
|
||
: T extends readonly [...NativeType[]] ? {
|
||
[K in keyof T]: FromNativeType<T[K]>;
|
||
}
|
||
: never;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The interface for a foreign function as defined by its parameter and result
|
||
* types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export interface ForeignFunction<
|
||
Parameters extends readonly NativeType[] = readonly NativeType[],
|
||
Result extends NativeResultType = NativeResultType,
|
||
NonBlocking extends boolean = boolean,
|
||
> {
|
||
/** Name of the symbol.
|
||
*
|
||
* Defaults to the key name in symbols object. */
|
||
name?: string;
|
||
/** The parameters of the foreign function. */
|
||
parameters: Parameters;
|
||
/** The result (return value) of the foreign function. */
|
||
result: Result;
|
||
/** When `true`, function calls will run on a dedicated blocking thread and
|
||
* will return a `Promise` resolving to the `result`. */
|
||
nonblocking?: NonBlocking;
|
||
/** When `true`, function calls can safely callback into JavaScript or
|
||
* trigger a garbage collection event.
|
||
*
|
||
* @default {false} */
|
||
callback?: boolean;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export interface ForeignStatic<Type extends NativeType = NativeType> {
|
||
/** Name of the symbol, defaults to the key name in symbols object. */
|
||
name?: string;
|
||
/** The type of the foreign static value. */
|
||
type: Type;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A foreign library interface descriptor.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export interface ForeignLibraryInterface {
|
||
[name: string]: ForeignFunction | ForeignStatic;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A utility type that infers a foreign symbol.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type StaticForeignSymbol<T extends ForeignFunction | ForeignStatic> =
|
||
T extends ForeignFunction ? FromForeignFunction<T>
|
||
: T extends ForeignStatic ? FromNativeType<T["type"]>
|
||
: never;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromForeignFunction<T extends ForeignFunction> = T["parameters"] extends
|
||
readonly [] ? () => StaticForeignSymbolReturnType<T>
|
||
: (
|
||
...args: ToNativeParameterTypes<T["parameters"]>
|
||
) => StaticForeignSymbolReturnType<T>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type StaticForeignSymbolReturnType<T extends ForeignFunction> =
|
||
ConditionalAsync<T["nonblocking"], FromNativeResultType<T["result"]>>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ConditionalAsync<IsAsync extends boolean | undefined, T> =
|
||
IsAsync extends true ? Promise<T> : T;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A utility type that infers a foreign library interface.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type StaticForeignLibraryInterface<T extends ForeignLibraryInterface> = {
|
||
[K in keyof T]: StaticForeignSymbol<T[K]>;
|
||
};
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Pointer type depends on the architecture and actual pointer value.
|
||
*
|
||
* On a 32 bit host system all pointer values are plain numbers. On a 64 bit
|
||
* host system pointer values are represented as numbers if the value is below
|
||
* `Number.MAX_SAFE_INTEGER`, otherwise they are provided as bigints.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export type PointerValue = number | bigint;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* An unsafe pointer to a memory location for passing and returning pointers
|
||
* to and from the FFI.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export class UnsafePointer {
|
||
/** Return the direct memory pointer to the typed array in memory. */
|
||
static of(value: Deno.UnsafeCallback | BufferSource): PointerValue;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* An unsafe pointer view to a memory location as specified by the `pointer`
|
||
* value. The `UnsafePointerView` API follows the standard built in interface
|
||
* {@linkcode DataView} for accessing the underlying types at an memory
|
||
* location (numbers, strings and raw bytes).
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export class UnsafePointerView {
|
||
constructor(pointer: PointerValue);
|
||
|
||
pointer: PointerValue;
|
||
|
||
/** Gets a boolean at the specified byte offset from the pointer. */
|
||
getBool(offset?: number): boolean;
|
||
/** Gets an unsigned 8-bit integer at the specified byte offset from the
|
||
* pointer. */
|
||
getUint8(offset?: number): number;
|
||
/** Gets a signed 8-bit integer at the specified byte offset from the
|
||
* pointer. */
|
||
getInt8(offset?: number): number;
|
||
/** Gets an unsigned 16-bit integer at the specified byte offset from the
|
||
* pointer. */
|
||
getUint16(offset?: number): number;
|
||
/** Gets a signed 16-bit integer at the specified byte offset from the
|
||
* pointer. */
|
||
getInt16(offset?: number): number;
|
||
/** Gets an unsigned 32-bit integer at the specified byte offset from the
|
||
* pointer. */
|
||
getUint32(offset?: number): number;
|
||
/** Gets a signed 32-bit integer at the specified byte offset from the
|
||
* pointer. */
|
||
getInt32(offset?: number): number;
|
||
/** Gets an unsigned 64-bit integer at the specified byte offset from the
|
||
* pointer. */
|
||
getBigUint64(offset?: number): PointerValue;
|
||
/** Gets a signed 64-bit integer at the specified byte offset from the
|
||
* pointer. */
|
||
getBigInt64(offset?: number): PointerValue;
|
||
/** Gets a signed 32-bit float at the specified byte offset from the
|
||
* pointer. */
|
||
getFloat32(offset?: number): number;
|
||
/** Gets a signed 64-bit float at the specified byte offset from the
|
||
* pointer. */
|
||
getFloat64(offset?: number): number;
|
||
/** Gets a C string (`null` terminated string) at the specified byte offset
|
||
* from the pointer. */
|
||
getCString(offset?: number): string;
|
||
/** Gets a C string (`null` terminated string) at the specified byte offset
|
||
* from the specified pointer. */
|
||
static getCString(pointer: PointerValue, offset?: number): string;
|
||
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
|
||
* offset from the pointer. */
|
||
getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer;
|
||
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
|
||
* offset from the specified pointer. */
|
||
static getArrayBuffer(
|
||
pointer: PointerValue,
|
||
byteLength: number,
|
||
offset?: number,
|
||
): ArrayBuffer;
|
||
/** Copies the memory of the pointer into a typed array.
|
||
*
|
||
* Length is determined from the typed array's `byteLength`.
|
||
*
|
||
* Also takes optional byte offset from the pointer. */
|
||
copyInto(destination: BufferSource, offset?: number): void;
|
||
/** Copies the memory of the specified pointer into a typed array.
|
||
*
|
||
* Length is determined from the typed array's `byteLength`.
|
||
*
|
||
* Also takes optional byte offset from the pointer. */
|
||
static copyInto(
|
||
pointer: PointerValue,
|
||
destination: BufferSource,
|
||
offset?: number,
|
||
): void;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* An unsafe pointer to a function, for calling functions that are not present
|
||
* as symbols.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export class UnsafeFnPointer<Fn extends ForeignFunction> {
|
||
/** The pointer to the function. */
|
||
pointer: PointerValue;
|
||
/** The definition of the function. */
|
||
definition: Fn;
|
||
|
||
constructor(pointer: PointerValue, definition: Const<Fn>);
|
||
|
||
/** Call the foreign function. */
|
||
call: FromForeignFunction<Fn>;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Definition of a unsafe callback function.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export interface UnsafeCallbackDefinition<
|
||
Parameters extends readonly NativeType[] = readonly NativeType[],
|
||
Result extends NativeResultType = NativeResultType,
|
||
> {
|
||
/** The parameters of the callbacks. */
|
||
parameters: Parameters;
|
||
/** The current result of the callback. */
|
||
result: Result;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* An unsafe callback function.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type UnsafeCallbackFunction<
|
||
Parameters extends readonly NativeType[] = readonly NativeType[],
|
||
Result extends NativeResultType = NativeResultType,
|
||
> = Parameters extends readonly [] ? () => ToNativeResultType<Result> : (
|
||
...args: FromNativeParameterTypes<Parameters>
|
||
) => ToNativeResultType<Result>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* An unsafe function pointer for passing JavaScript functions as C function
|
||
* pointers to foreign function calls.
|
||
*
|
||
* The function pointer remains valid until the `close()` method is called.
|
||
*
|
||
* The callback can be explicitly referenced via `ref()` and dereferenced via
|
||
* `deref()` to stop Deno's process from exiting.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export class UnsafeCallback<
|
||
Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition,
|
||
> {
|
||
constructor(
|
||
definition: Const<Definition>,
|
||
callback: UnsafeCallbackFunction<
|
||
Definition["parameters"],
|
||
Definition["result"]
|
||
>,
|
||
);
|
||
|
||
/** The pointer to the unsafe callback. */
|
||
pointer: PointerValue;
|
||
/** The definition of the unsafe callback. */
|
||
definition: Definition;
|
||
/** The callback function. */
|
||
callback: UnsafeCallbackFunction<
|
||
Definition["parameters"],
|
||
Definition["result"]
|
||
>;
|
||
|
||
/**
|
||
* Adds one to this callback's reference counting and returns the new
|
||
* reference count.
|
||
*
|
||
* If the callback's reference count is non-zero, it will keep Deno's
|
||
* process from exiting.
|
||
*/
|
||
ref(): number;
|
||
|
||
/**
|
||
* Removes one from this callback's reference counting and returns the new
|
||
* reference count.
|
||
*
|
||
* If the callback's reference counter is zero, it will no longer keep
|
||
* Deno's process from exiting.
|
||
*/
|
||
unref(): number;
|
||
|
||
/**
|
||
* Removes the C function pointer associated with this instance.
|
||
*
|
||
* Continuing to use the instance after calling this object will lead to
|
||
* errors and crashes.
|
||
*
|
||
* Calling this method will also immediately set the callback's reference
|
||
* counting to zero and it will no longer keep Deno's process from exiting.
|
||
*/
|
||
close(): void;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic
|
||
* library and return this interface.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export interface DynamicLibrary<S extends ForeignLibraryInterface> {
|
||
/** All of the registered library along with functions for calling them. */
|
||
symbols: StaticForeignLibraryInterface<S>;
|
||
/** Removes the pointers associated with the library symbols.
|
||
*
|
||
* Continuing to use symbols that are part of the library will lead to
|
||
* errors and crashes.
|
||
*
|
||
* Calling this method will also immediately set any references to zero and
|
||
* will no longer keep Deno's process from exiting.
|
||
*/
|
||
close(): void;
|
||
}
|
||
|
||
/**
|
||
* This magic code used to implement better type hints for {@linkcode Deno.dlopen}
|
||
*/
|
||
type Cast<A, B> = A extends B ? A : B;
|
||
type Const<T> = Cast<
|
||
T,
|
||
| (T extends string | number | bigint | boolean ? T : never)
|
||
| { [K in keyof T]: Const<T[K]> }
|
||
| []
|
||
>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Opens an external dynamic library and registers symbols, making foreign
|
||
* functions available to be called.
|
||
*
|
||
* Requires `allow-ffi` permission. Loading foreign dynamic libraries can in
|
||
* theory bypass all of the sandbox permissions. While it is a separate
|
||
* permission users should acknowledge in practice that is effectively the
|
||
* same as running with the `allow-all` permission.
|
||
*
|
||
* @example Given a C library which exports a foreign function named `add()`
|
||
*
|
||
* ```ts
|
||
* // Determine library extension based on
|
||
* // your OS.
|
||
* let libSuffix = "";
|
||
* switch (Deno.build.os) {
|
||
* case "windows":
|
||
* libSuffix = "dll";
|
||
* break;
|
||
* case "darwin":
|
||
* libSuffix = "dylib";
|
||
* break;
|
||
* default:
|
||
* libSuffix = "so";
|
||
* break;
|
||
* }
|
||
*
|
||
* const libName = `./libadd.${libSuffix}`;
|
||
* // Open library and define exported symbols
|
||
* const dylib = Deno.dlopen(
|
||
* libName,
|
||
* {
|
||
* "add": { parameters: ["isize", "isize"], result: "isize" },
|
||
* } as const,
|
||
* );
|
||
*
|
||
* // Call the symbol `add`
|
||
* const result = dylib.symbols.add(35, 34); // 69
|
||
*
|
||
* console.log(`Result from external addition of 35 and 34: ${result}`);
|
||
* ```
|
||
*
|
||
* @tags allow-ffi
|
||
* @category FFI
|
||
*/
|
||
export function dlopen<S extends ForeignLibraryInterface>(
|
||
filename: string | URL,
|
||
symbols: Const<S>,
|
||
): DynamicLibrary<S>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* These are unstable options which can be used with {@linkcode Deno.run}.
|
||
*
|
||
* @category Sub Process
|
||
*/
|
||
interface UnstableRunOptions extends RunOptions {
|
||
/** If `true`, clears the environment variables before executing the
|
||
* sub-process.
|
||
*
|
||
* @default {false} */
|
||
clearEnv?: boolean;
|
||
/** For POSIX systems, sets the group ID for the sub process. */
|
||
gid?: number;
|
||
/** For POSIX systems, sets the user ID for the sub process. */
|
||
uid?: number;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`,
|
||
* an array of program arguments, the first of which is the binary.
|
||
*
|
||
* ```ts
|
||
* const p = Deno.run({
|
||
* cmd: ["curl", "https://example.com"],
|
||
* });
|
||
* const status = await p.status();
|
||
* ```
|
||
*
|
||
* Subprocess uses same working directory as parent process unless `opt.cwd`
|
||
* is specified.
|
||
*
|
||
* Environmental variables from parent process can be cleared using `opt.clearEnv`.
|
||
* Doesn't guarantee that only `opt.env` variables are present,
|
||
* as the OS may set environmental variables for processes.
|
||
*
|
||
* Environmental variables for subprocess can be specified using `opt.env`
|
||
* mapping.
|
||
*
|
||
* `opt.uid` sets the child process’s user ID. This translates to a setuid call
|
||
* in the child process. Failure in the setuid call will cause the spawn to fail.
|
||
*
|
||
* `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process.
|
||
* This has the same semantics as the uid field.
|
||
*
|
||
* By default subprocess inherits stdio of parent process. To change
|
||
* this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set
|
||
* independently to a resource ID (_rid_) of an open file, `"inherit"`,
|
||
* `"piped"`, or `"null"`:
|
||
*
|
||
* - _number_: the resource ID of an open file/resource. This allows you to
|
||
* read or write to a file.
|
||
* - `"inherit"`: The default if unspecified. The subprocess inherits from the
|
||
* parent.
|
||
* - `"piped"`: A new pipe should be arranged to connect the parent and child
|
||
* sub-process.
|
||
* - `"null"`: This stream will be ignored. This is the equivalent of attaching
|
||
* the stream to `/dev/null`.
|
||
*
|
||
* Details of the spawned process are returned as an instance of
|
||
* {@linkcode Deno.Process}.
|
||
*
|
||
* Requires `allow-run` permission.
|
||
*
|
||
* @tags allow-run
|
||
* @category Sub Process
|
||
*/
|
||
export function run<T extends UnstableRunOptions = UnstableRunOptions>(
|
||
opt: T,
|
||
): Process<T>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A custom `HttpClient` for use with {@linkcode fetch} function. This is
|
||
* designed to allow custom certificates or proxies to be used with `fetch()`.
|
||
*
|
||
* @example ```ts
|
||
* const caCert = await Deno.readTextFile("./ca.pem");
|
||
* const client = Deno.createHttpClient({ caCerts: [ caCert ] });
|
||
* const req = await fetch("https://myserver.com", { client });
|
||
* ```
|
||
*
|
||
* @category Fetch API
|
||
*/
|
||
export interface HttpClient {
|
||
/** The resource ID associated with the client. */
|
||
rid: number;
|
||
/** Close the HTTP client. */
|
||
close(): void;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The options used when creating a {@linkcode Deno.HttpClient}.
|
||
*
|
||
* @category Fetch API
|
||
*/
|
||
export interface CreateHttpClientOptions {
|
||
/** A list of root certificates that will be used in addition to the
|
||
* default root certificates to verify the peer's certificate.
|
||
*
|
||
* Must be in PEM format. */
|
||
caCerts?: string[];
|
||
/** A HTTP proxy to use for new connections. */
|
||
proxy?: Proxy;
|
||
/** PEM formatted client certificate chain. */
|
||
certChain?: string;
|
||
/** PEM formatted (RSA or PKCS8) private key of client certificate. */
|
||
privateKey?: string;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The definition of a proxy when specifying
|
||
* {@linkcode Deno.CreateHttpClientOptions}.
|
||
*
|
||
* @category Fetch API
|
||
*/
|
||
export interface Proxy {
|
||
/** The string URL of the proxy server to use. */
|
||
url: string;
|
||
/** The basic auth credentials to be used against the proxy server. */
|
||
basicAuth?: BasicAuth;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Basic authentication credentials to be used with a {@linkcode Deno.Proxy}
|
||
* server when specifying {@linkcode Deno.CreateHttpClientOptions}.
|
||
*
|
||
* @category Fetch API
|
||
*/
|
||
export interface BasicAuth {
|
||
/** The username to be used against the proxy server. */
|
||
username: string;
|
||
/** The password to be used against the proxy server. */
|
||
password: string;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Create a custom HttpClient for to use with {@linkcode fetch}. This is an
|
||
* extension of the web platform Fetch API which allows Deno to use custom
|
||
* TLS certificates and connect via a proxy while using `fetch()`.
|
||
*
|
||
* @example ```ts
|
||
* const caCert = await Deno.readTextFile("./ca.pem");
|
||
* const client = Deno.createHttpClient({ caCerts: [ caCert ] });
|
||
* const response = await fetch("https://myserver.com", { client });
|
||
* ```
|
||
*
|
||
* @example ```ts
|
||
* const client = Deno.createHttpClient({
|
||
* proxy: { url: "http://myproxy.com:8080" }
|
||
* });
|
||
* const response = await fetch("https://myserver.com", { client });
|
||
* ```
|
||
*
|
||
* @category Fetch API
|
||
*/
|
||
export function createHttpClient(
|
||
options: CreateHttpClientOptions,
|
||
): HttpClient;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A generic transport listener for message-oriented protocols.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> {
|
||
/** Waits for and resolves to the next message to the instance.
|
||
*
|
||
* Messages are received in the format of a tuple containing the data array
|
||
* and the address information.
|
||
*/
|
||
receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>;
|
||
/** Sends a message to the target via the connection. The method resolves
|
||
* with the number of bytes sent. */
|
||
send(p: Uint8Array, addr: Addr): Promise<number>;
|
||
/** Close closes the socket. Any pending message promises will be rejected
|
||
* with errors. */
|
||
close(): void;
|
||
/** Return the address of the instance. */
|
||
readonly addr: Addr;
|
||
[Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>;
|
||
}
|
||
|
||
/**
|
||
* @category Network
|
||
*/
|
||
export interface TcpListenOptions extends ListenOptions {
|
||
/** When `true` the SO_REUSEPORT flag will be set on the listener. This
|
||
* allows multiple processes to listen on the same address and port.
|
||
*
|
||
* On Linux this will cause the kernel to distribute incoming connections
|
||
* across the different processes that are listening on the same address and
|
||
* port.
|
||
*
|
||
* This flag is only supported on Linux. It is silently ignored on other
|
||
* platforms.
|
||
*
|
||
* @default {false} */
|
||
reusePort?: boolean;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Unstable options which can be set when opening a Unix listener via
|
||
* {@linkcode Deno.listen} or {@linkcode Deno.listenDatagram}.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface UnixListenOptions {
|
||
/** A path to the Unix Socket. */
|
||
path: string;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Unstable options which can be set when opening a datagram listener via
|
||
* {@linkcode Deno.listenDatagram}.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface UdpListenOptions extends ListenOptions {
|
||
/** When `true` the specified address will be reused, even if another
|
||
* process has already bound a socket on it. This effectively steals the
|
||
* socket from the listener.
|
||
*
|
||
* @default {false} */
|
||
reuseAddress?: boolean;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Listen announces on the local transport address.
|
||
*
|
||
* ```ts
|
||
* const listener = Deno.listen({ path: "/foo/bar.sock", transport: "unix" })
|
||
* ```
|
||
*
|
||
* Requires `allow-read` and `allow-write` permission.
|
||
*
|
||
* @tags allow-read, allow-write
|
||
* @category Network
|
||
*/
|
||
export function listen(
|
||
options: UnixListenOptions & { transport: "unix" },
|
||
): Listener;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Listen announces on the local transport address.
|
||
*
|
||
* ```ts
|
||
* const listener1 = Deno.listenDatagram({
|
||
* port: 80,
|
||
* transport: "udp"
|
||
* });
|
||
* const listener2 = Deno.listenDatagram({
|
||
* hostname: "golang.org",
|
||
* port: 80,
|
||
* transport: "udp"
|
||
* });
|
||
* ```
|
||
*
|
||
* Requires `allow-net` permission.
|
||
*
|
||
* @tags allow-net
|
||
* @category Network
|
||
*/
|
||
export function listenDatagram(
|
||
options: UdpListenOptions & { transport: "udp" },
|
||
): DatagramConn;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Listen announces on the local transport address.
|
||
*
|
||
* ```ts
|
||
* const listener = Deno.listenDatagram({
|
||
* path: "/foo/bar.sock",
|
||
* transport: "unixpacket"
|
||
* });
|
||
* ```
|
||
*
|
||
* Requires `allow-read` and `allow-write` permission.
|
||
*
|
||
* @tags allow-read, allow-write
|
||
* @category Network
|
||
*/
|
||
export function listenDatagram(
|
||
options: UnixListenOptions & { transport: "unixpacket" },
|
||
): DatagramConn;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface UnixConnectOptions {
|
||
transport: "unix";
|
||
path: string;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Connects to the hostname (default is "127.0.0.1") and port on the named
|
||
* transport (default is "tcp"), and resolves to the connection (`Conn`).
|
||
*
|
||
* ```ts
|
||
* const conn1 = await Deno.connect({ port: 80 });
|
||
* const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 });
|
||
* const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 });
|
||
* const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" });
|
||
* const conn5 = await Deno.connect({ path: "/foo/bar.sock", transport: "unix" });
|
||
* ```
|
||
*
|
||
* Requires `allow-net` permission for "tcp" and `allow-read` for "unix".
|
||
*
|
||
* @tags allow-net, allow-read
|
||
* @category Network
|
||
*/
|
||
export function connect(options: ConnectOptions): Promise<TcpConn>;
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Connects to the hostname (default is "127.0.0.1") and port on the named
|
||
* transport (default is "tcp"), and resolves to the connection (`Conn`).
|
||
*
|
||
* ```ts
|
||
* const conn1 = await Deno.connect({ port: 80 });
|
||
* const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 });
|
||
* const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 });
|
||
* const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" });
|
||
* const conn5 = await Deno.connect({ path: "/foo/bar.sock", transport: "unix" });
|
||
* ```
|
||
*
|
||
* Requires `allow-net` permission for "tcp" and `allow-read` for "unix".
|
||
*
|
||
* @tags allow-net, allow-read
|
||
* @category Network
|
||
*/
|
||
export function connect(options: UnixConnectOptions): Promise<UnixConn>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface ConnectTlsOptions {
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* PEM formatted client certificate chain.
|
||
*/
|
||
certChain?: string;
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* PEM formatted (RSA or PKCS8) private key of client certificate.
|
||
*/
|
||
privateKey?: string;
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Application-Layer Protocol Negotiation (ALPN) protocols supported by
|
||
* the client. If not specified, no ALPN extension will be included in the
|
||
* TLS handshake.
|
||
*/
|
||
alpnProtocols?: string[];
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface TlsHandshakeInfo {
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Contains the ALPN protocol selected during negotiation with the server.
|
||
* If no ALPN protocol selected, returns `null`.
|
||
*/
|
||
alpnProtocol: string | null;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface TlsConn extends Conn {
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Runs the client or server handshake protocol to completion if that has
|
||
* not happened yet. Calling this method is optional; the TLS handshake
|
||
* will be completed automatically as soon as data is sent or received.
|
||
*/
|
||
handshake(): Promise<TlsHandshakeInfo>;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Create a TLS connection with an attached client certificate.
|
||
*
|
||
* ```ts
|
||
* const conn = await Deno.connectTls({
|
||
* hostname: "deno.land",
|
||
* port: 443,
|
||
* certChain: "---- BEGIN CERTIFICATE ----\n ...",
|
||
* privateKey: "---- BEGIN PRIVATE KEY ----\n ...",
|
||
* });
|
||
* ```
|
||
*
|
||
* Requires `allow-net` permission.
|
||
*
|
||
* @tags allow-net
|
||
* @category Network
|
||
*/
|
||
export function connectTls(options: ConnectTlsOptions): Promise<TlsConn>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface ListenTlsOptions {
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Application-Layer Protocol Negotiation (ALPN) protocols to announce to
|
||
* the client. If not specified, no ALPN extension will be included in the
|
||
* TLS handshake.
|
||
*/
|
||
alpnProtocols?: string[];
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Network
|
||
*/
|
||
export interface StartTlsOptions {
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Application-Layer Protocol Negotiation (ALPN) protocols to announce to
|
||
* the client. If not specified, no ALPN extension will be included in the
|
||
* TLS handshake.
|
||
*/
|
||
alpnProtocols?: string[];
|
||
}
|
||
|
||
/** @category Network */
|
||
export interface Listener extends AsyncIterable<Conn> {
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Make the listener block the event loop from finishing.
|
||
*
|
||
* Note: the listener blocks the event loop from finishing by default.
|
||
* This method is only meaningful after `.unref()` is called.
|
||
*/
|
||
ref(): void;
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Make the listener not block the event loop from finishing.
|
||
*/
|
||
unref(): void;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Acquire an advisory file-system lock for the provided file.
|
||
*
|
||
* @param [exclusive=false]
|
||
* @category File System
|
||
*/
|
||
export function flock(rid: number, exclusive?: boolean): Promise<void>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Acquire an advisory file-system lock synchronously for the provided file.
|
||
*
|
||
* @param [exclusive=false]
|
||
* @category File System
|
||
*/
|
||
export function flockSync(rid: number, exclusive?: boolean): void;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Release an advisory file-system lock for the provided file.
|
||
*
|
||
* @category File System
|
||
*/
|
||
export function funlock(rid: number): Promise<void>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Release an advisory file-system lock for the provided file synchronously.
|
||
*
|
||
* @category File System
|
||
*/
|
||
export function funlockSync(rid: number): void;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* A handler for HTTP requests. Consumes a request and returns a response.
|
||
*
|
||
* If a handler throws, the server calling the handler will assume the impact
|
||
* of the error is isolated to the individual request. It will catch the error
|
||
* and if necessary will close the underlying connection.
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export type ServeHandler = (request: Request) => Response | Promise<Response>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Options which can be set when calling {@linkcode Deno.serve}.
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export interface ServeOptions extends Partial<Deno.ListenOptions> {
|
||
/** An {@linkcode AbortSignal} to close the server and all connections. */
|
||
signal?: AbortSignal;
|
||
|
||
/** Sets `SO_REUSEPORT` on POSIX systems. */
|
||
reusePort?: boolean;
|
||
|
||
/** The handler to invoke when route handlers throw an error. */
|
||
onError?: (error: unknown) => Response | Promise<Response>;
|
||
|
||
/** The callback which is called when the server starts listening. */
|
||
onListen?: (params: { hostname: string; port: number }) => void;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Additional options which are used when opening a TLS (HTTPS) server.
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export interface ServeTlsOptions extends ServeOptions {
|
||
/** Server private key in PEM format */
|
||
cert: string;
|
||
|
||
/** Cert chain in PEM format */
|
||
key: string;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export interface ServeInit {
|
||
/** The handler to invoke to process each incoming request. */
|
||
handler: ServeHandler;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Serves HTTP requests with the given handler.
|
||
*
|
||
* You can specify an object with a port and hostname option, which is the
|
||
* address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
|
||
*
|
||
* The below example serves with the port `9000`.
|
||
*
|
||
* ```ts
|
||
* Deno.serve((_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* You can change the address to listen on using the `hostname` and `port`
|
||
* options. The below example serves on port `3000`.
|
||
*
|
||
* ```ts
|
||
* Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* You can stop the server with an {@linkcode AbortSignal}. The abort signal
|
||
* needs to be passed as the `signal` option in the options bag. The server
|
||
* aborts when the abort signal is aborted. To wait for the server to close,
|
||
* await the promise returned from the `Deno.serve` API.
|
||
*
|
||
* ```ts
|
||
* const ac = new AbortController();
|
||
*
|
||
* Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world"))
|
||
* .then(() => console.log("Server closed"));
|
||
*
|
||
* console.log("Closing server...");
|
||
* ac.abort();
|
||
* ```
|
||
*
|
||
* By default `Deno.serve` prints the message
|
||
* `Listening on http://<hostname>:<port>/` on listening. If you like to
|
||
* change this behavior, you can specify a custom `onListen` callback.
|
||
*
|
||
* ```ts
|
||
* Deno.serve({
|
||
* onListen({ port, hostname }) {
|
||
* console.log(`Server started at http://${hostname}:${port}`);
|
||
* // ... more info specific to your server ..
|
||
* },
|
||
* handler: (_req) => new Response("Hello, world"),
|
||
* });
|
||
* ```
|
||
*
|
||
* To enable TLS you must specify the `key` and `cert` options.
|
||
*
|
||
* ```ts
|
||
* const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
|
||
* const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
|
||
* Deno.serve({ cert, key }, (_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export function serve(
|
||
handler: ServeHandler,
|
||
options?: ServeOptions | ServeTlsOptions,
|
||
): Promise<void>;
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Serves HTTP requests with the given handler.
|
||
*
|
||
* You can specify an object with a port and hostname option, which is the
|
||
* address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
|
||
*
|
||
* The below example serves with the port `9000`.
|
||
*
|
||
* ```ts
|
||
* Deno.serve((_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* You can change the address to listen on using the `hostname` and `port`
|
||
* options. The below example serves on port `3000`.
|
||
*
|
||
* ```ts
|
||
* Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* You can stop the server with an {@linkcode AbortSignal}. The abort signal
|
||
* needs to be passed as the `signal` option in the options bag. The server
|
||
* aborts when the abort signal is aborted. To wait for the server to close,
|
||
* await the promise returned from the `Deno.serve` API.
|
||
*
|
||
* ```ts
|
||
* const ac = new AbortController();
|
||
*
|
||
* Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world"))
|
||
* .then(() => console.log("Server closed"));
|
||
*
|
||
* console.log("Closing server...");
|
||
* ac.abort();
|
||
* ```
|
||
*
|
||
* By default `Deno.serve` prints the message
|
||
* `Listening on http://<hostname>:<port>/` on listening. If you like to
|
||
* change this behavior, you can specify a custom `onListen` callback.
|
||
*
|
||
* ```ts
|
||
* Deno.serve({
|
||
* onListen({ port, hostname }) {
|
||
* console.log(`Server started at http://${hostname}:${port}`);
|
||
* // ... more info specific to your server ..
|
||
* },
|
||
* handler: (_req) => new Response("Hello, world"),
|
||
* });
|
||
* ```
|
||
*
|
||
* To enable TLS you must specify the `key` and `cert` options.
|
||
*
|
||
* ```ts
|
||
* const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
|
||
* const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
|
||
* Deno.serve({ cert, key }, (_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export function serve(
|
||
options: ServeOptions | ServeTlsOptions,
|
||
handler: ServeHandler,
|
||
): Promise<void>;
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Serves HTTP requests with the given handler.
|
||
*
|
||
* You can specify an object with a port and hostname option, which is the
|
||
* address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
|
||
*
|
||
* The below example serves with the port `9000`.
|
||
*
|
||
* ```ts
|
||
* Deno.serve((_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* You can change the address to listen on using the `hostname` and `port`
|
||
* options. The below example serves on port `3000`.
|
||
*
|
||
* ```ts
|
||
* Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* You can stop the server with an {@linkcode AbortSignal}. The abort signal
|
||
* needs to be passed as the `signal` option in the options bag. The server
|
||
* aborts when the abort signal is aborted. To wait for the server to close,
|
||
* await the promise returned from the `Deno.serve` API.
|
||
*
|
||
* ```ts
|
||
* const ac = new AbortController();
|
||
*
|
||
* Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world"))
|
||
* .then(() => console.log("Server closed"));
|
||
*
|
||
* console.log("Closing server...");
|
||
* ac.abort();
|
||
* ```
|
||
*
|
||
* By default `Deno.serve` prints the message
|
||
* `Listening on http://<hostname>:<port>/` on listening. If you like to
|
||
* change this behavior, you can specify a custom `onListen` callback.
|
||
*
|
||
* ```ts
|
||
* Deno.serve({
|
||
* onListen({ port, hostname }) {
|
||
* console.log(`Server started at http://${hostname}:${port}`);
|
||
* // ... more info specific to your server ..
|
||
* },
|
||
* handler: (_req) => new Response("Hello, world"),
|
||
* });
|
||
* ```
|
||
*
|
||
* To enable TLS you must specify the `key` and `cert` options.
|
||
*
|
||
* ```ts
|
||
* const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
|
||
* const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
|
||
* Deno.serve({ cert, key }, (_req) => new Response("Hello, world"));
|
||
* ```
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export function serve(
|
||
options: ServeInit & (ServeOptions | ServeTlsOptions),
|
||
): Promise<void>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Allows "hijacking" the connection that the request is associated with. This
|
||
* can be used to implement protocols that build on top of HTTP (eg.
|
||
* {@linkcode WebSocket}).
|
||
*
|
||
* The returned promise returns underlying connection and first packet
|
||
* received. The promise shouldn't be awaited before responding to the
|
||
* `request`, otherwise event loop might deadlock.
|
||
*
|
||
* ```ts
|
||
* function handler(req: Request): Response {
|
||
* Deno.upgradeHttp(req).then(([conn, firstPacket]) => {
|
||
* // ...
|
||
* });
|
||
* return new Response(null, { status: 101 });
|
||
* }
|
||
* ```
|
||
*
|
||
* This method can only be called on requests originating the
|
||
* {@linkcode Deno.serveHttp} server.
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export function upgradeHttp(
|
||
request: Request,
|
||
): Promise<[Deno.Conn, Uint8Array]>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Allows "hijacking" the connection that the request is associated with.
|
||
* This can be used to implement protocols that build on top of HTTP (eg.
|
||
* {@linkcode WebSocket}).
|
||
*
|
||
* Unlike {@linkcode Deno.upgradeHttp} this function does not require that you
|
||
* respond to the request with a {@linkcode Response} object. Instead this
|
||
* function returns the underlying connection and first packet received
|
||
* immediately, and then the caller is responsible for writing the response to
|
||
* the connection.
|
||
*
|
||
* This method can only be called on requests originating the
|
||
* {@linkcode Deno.serve} server.
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export function upgradeHttpRaw(request: Request): [Deno.Conn, Uint8Array];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @deprecated Use the Deno.Command API instead.
|
||
*
|
||
* Options which can be set when calling {@linkcode Deno.spawn},
|
||
* {@linkcode Deno.spawnSync}, and {@linkcode Deno.spawnChild}.
|
||
*
|
||
* @category Sub Process
|
||
*/
|
||
export interface SpawnOptions {
|
||
/** Arguments to pass to the process. */
|
||
args?: string[];
|
||
/**
|
||
* The working directory of the process.
|
||
*
|
||
* If not specified, the `cwd` of the parent process is used.
|
||
*/
|
||
cwd?: string | URL;
|
||
/**
|
||
* Clear environmental variables from parent process.
|
||
*
|
||
* Doesn't guarantee that only `env` variables are present, as the OS may
|
||
* set environmental variables for processes.
|
||
*
|
||
* @default {false}
|
||
*/
|
||
clearEnv?: boolean;
|
||
/** Environmental variables to pass to the subprocess. */
|
||
env?: Record<string, string>;
|
||
/**
|
||
* Sets the child process’s user ID. This translates to a setuid call in the
|
||
* child process. Failure in the set uid call will cause the spawn to fail.
|
||
*/
|
||
uid?: number;
|
||
/** Similar to `uid`, but sets the group ID of the child process. */
|
||
gid?: number;
|
||
/**
|
||
* An {@linkcode AbortSignal} that allows closing the process using the
|
||
* corresponding {@linkcode AbortController} by sending the process a
|
||
* SIGTERM signal.
|
||
*
|
||
* Not supported in {@linkcode Deno.spawnSync}.
|
||
*/
|
||
signal?: AbortSignal;
|
||
|
||
/** How `stdin` of the spawned process should be handled.
|
||
*
|
||
* Defaults to `"null"`. */
|
||
stdin?: "piped" | "inherit" | "null";
|
||
/** How `stdout` of the spawned process should be handled.
|
||
*
|
||
* Defaults to `"piped". */
|
||
stdout?: "piped" | "inherit" | "null";
|
||
/** How `stderr` of the spawned process should be handled.
|
||
*
|
||
* Defaults to `"piped"`. */
|
||
stderr?: "piped" | "inherit" | "null";
|
||
|
||
/** Skips quoting and escaping of the arguments on windows. This option
|
||
* is ignored on non-windows platforms.
|
||
*
|
||
* @default {false} */
|
||
windowsRawArguments?: boolean;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Create a child process.
|
||
*
|
||
* If any stdio options are not set to `"piped"`, accessing the corresponding
|
||
* field on the `Command` or its `CommandOutput` will throw a `TypeError`.
|
||
*
|
||
* If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream}
|
||
* needs to be closed manually.
|
||
*
|
||
* @example Spawn a subprocess and pipe the output to a file
|
||
*
|
||
* ```ts
|
||
* const command = new Deno.Command(Deno.execPath(), {
|
||
* args: [
|
||
* "eval",
|
||
* "console.log('Hello World')",
|
||
* ],
|
||
* stdin: "piped",
|
||
* });
|
||
* const child = command.spawn();
|
||
*
|
||
* // open a file and pipe the subprocess output to it.
|
||
* child.stdout.pipeTo(Deno.openSync("output").writable);
|
||
*
|
||
* // manually close stdin
|
||
* child.stdin.close();
|
||
* const status = await child.status;
|
||
* ```
|
||
*
|
||
* @example Spawn a subprocess and collect its output
|
||
*
|
||
* ```ts
|
||
* const command = new Deno.Command(Deno.execPath(), {
|
||
* args: [
|
||
* "eval",
|
||
* "console.log('hello'); console.error('world')",
|
||
* ],
|
||
* });
|
||
* const { code, stdout, stderr } = await command.output();
|
||
* console.assert(code === 0);
|
||
* console.assert("hello\n" === new TextDecoder().decode(stdout));
|
||
* console.assert("world\n" === new TextDecoder().decode(stderr));
|
||
* ```
|
||
*
|
||
* @example Spawn a subprocess and collect its output synchronously
|
||
*
|
||
* ```ts
|
||
* const command = new Deno.Command(Deno.execPath(), {
|
||
* args: [
|
||
* "eval",
|
||
* "console.log('hello'); console.error('world')",
|
||
* ],
|
||
* });
|
||
* const { code, stdout, stderr } = command.outputSync();
|
||
* console.assert(code === 0);
|
||
* console.assert("hello\n" === new TextDecoder().decode(stdout));
|
||
* console.assert("world\n" === new TextDecoder().decode(stderr));
|
||
* ```
|
||
*
|
||
* @category Sub Process
|
||
*/
|
||
export class Command {
|
||
constructor(command: string | URL, options?: CommandOptions);
|
||
/**
|
||
* Executes the {@linkcode Deno.Command}, waiting for it to finish and
|
||
* collecting all of its output.
|
||
* If `spawn()` was called, calling this function will collect the remaining
|
||
* output.
|
||
*
|
||
* Will throw an error if `stdin: "piped"` is set.
|
||
*
|
||
* If options `stdout` or `stderr` are not set to `"piped"`, accessing the
|
||
* corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`.
|
||
*/
|
||
output(): Promise<CommandOutput>;
|
||
/**
|
||
* Synchronously executes the {@linkcode Deno.Command}, waiting for it to
|
||
* finish and collecting all of its output.
|
||
*
|
||
* Will throw an error if `stdin: "piped"` is set.
|
||
*
|
||
* If options `stdout` or `stderr` are not set to `"piped"`, accessing the
|
||
* corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`.
|
||
*/
|
||
outputSync(): CommandOutput;
|
||
/**
|
||
* Spawns a streamable subprocess, allowing to use the other methods.
|
||
*/
|
||
spawn(): ChildProcess;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The interface for handling a child process returned from
|
||
* {@linkcode Deno.Command.spawn}.
|
||
*
|
||
* @category Sub Process
|
||
*/
|
||
export class ChildProcess {
|
||
get stdin(): WritableStream<Uint8Array>;
|
||
get stdout(): ReadableStream<Uint8Array>;
|
||
get stderr(): ReadableStream<Uint8Array>;
|
||
readonly pid: number;
|
||
/** Get the status of the child. */
|
||
readonly status: Promise<CommandStatus>;
|
||
|
||
/** Waits for the child to exit completely, returning all its output and
|
||
* status. */
|
||
output(): Promise<CommandOutput>;
|
||
/** Kills the process with given {@linkcode Deno.Signal}.
|
||
*
|
||
* @param [signo="SIGTERM"]
|
||
*/
|
||
kill(signo?: Signal): void;
|
||
|
||
/** Ensure that the status of the child process prevents the Deno process
|
||
* from exiting. */
|
||
ref(): void;
|
||
/** Ensure that the status of the child process does not block the Deno
|
||
* process from exiting. */
|
||
unref(): void;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Options which can be set when calling {@linkcode Deno.command}.
|
||
*
|
||
* @category Sub Process
|
||
*/
|
||
export interface CommandOptions {
|
||
/** Arguments to pass to the process. */
|
||
args?: string[];
|
||
/**
|
||
* The working directory of the process.
|
||
*
|
||
* If not specified, the `cwd` of the parent process is used.
|
||
*/
|
||
cwd?: string | URL;
|
||
/**
|
||
* Clear environmental variables from parent process.
|
||
*
|
||
* Doesn't guarantee that only `env` variables are present, as the OS may
|
||
* set environmental variables for processes.
|
||
*
|
||
* @default {false}
|
||
*/
|
||
clearEnv?: boolean;
|
||
/** Environmental variables to pass to the subprocess. */
|
||
env?: Record<string, string>;
|
||
/**
|
||
* Sets the child process’s user ID. This translates to a setuid call in the
|
||
* child process. Failure in the set uid call will cause the spawn to fail.
|
||
*/
|
||
uid?: number;
|
||
/** Similar to `uid`, but sets the group ID of the child process. */
|
||
gid?: number;
|
||
/**
|
||
* An {@linkcode AbortSignal} that allows closing the process using the
|
||
* corresponding {@linkcode AbortController} by sending the process a
|
||
* SIGTERM signal.
|
||
*
|
||
* Not supported in {@linkcode Deno.spawnSync}.
|
||
*/
|
||
signal?: AbortSignal;
|
||
|
||
/** How `stdin` of the spawned process should be handled.
|
||
*
|
||
* Defaults to `"null"`. */
|
||
stdin?: "piped" | "inherit" | "null";
|
||
/** How `stdout` of the spawned process should be handled.
|
||
*
|
||
* Defaults to `"piped"` for `output` & `outputSync`,
|
||
* and `"inherit"` for `spawn`. */
|
||
stdout?: "piped" | "inherit" | "null";
|
||
/** How `stderr` of the spawned process should be handled.
|
||
*
|
||
* Defaults to `"piped"` for `output` & `outputSync`,
|
||
* and `"inherit"` for `spawn`. */
|
||
stderr?: "piped" | "inherit" | "null";
|
||
|
||
/** Skips quoting and escaping of the arguments on windows. This option
|
||
* is ignored on non-windows platforms.
|
||
*
|
||
* @default {false} */
|
||
windowsRawArguments?: boolean;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Sub Process
|
||
*/
|
||
export interface CommandStatus {
|
||
/** If the child process exits with a 0 status code, `success` will be set
|
||
* to `true`, otherwise `false`. */
|
||
success: boolean;
|
||
/** The exit code of the child process. */
|
||
code: number;
|
||
/** The signal associated with the child process. */
|
||
signal: Signal | null;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The interface returned from calling {@linkcode Command.output} or
|
||
* {@linkcode Command.outputSync} which represents the result of spawning the
|
||
* child process.
|
||
*
|
||
* @category Sub Process
|
||
*/
|
||
export interface CommandOutput extends CommandStatus {
|
||
/** The buffered output from the child process' `stdout`. */
|
||
readonly stdout: Uint8Array;
|
||
/** The buffered output from the child process' `stderr`. */
|
||
readonly stderr: Uint8Array;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Returns the Operating System uptime in number of seconds.
|
||
*
|
||
* ```ts
|
||
* console.log(Deno.osUptime());
|
||
* ```
|
||
*
|
||
* Requires `allow-sys` permission.
|
||
*
|
||
* @tags allow-sys
|
||
* @category Runtime Environment
|
||
*/
|
||
export function osUptime(): number;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* The [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
|
||
* which also supports setting a {@linkcode Deno.HttpClient} which provides a
|
||
* way to connect via proxies and use custom TLS certificates.
|
||
*
|
||
* @tags allow-net, allow-read
|
||
* @category Fetch API
|
||
*/
|
||
declare function fetch(
|
||
input: Request | URL | string,
|
||
init?: RequestInit & { client: Deno.HttpClient },
|
||
): Promise<Response>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Web Workers
|
||
*/
|
||
declare interface WorkerOptions {
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Configure permissions options to change the level of access the worker will
|
||
* have. By default it will have no permissions. Note that the permissions
|
||
* of a worker can't be extended beyond its parent's permissions reach.
|
||
*
|
||
* - `"inherit"` will take the permissions of the thread the worker is created
|
||
* in.
|
||
* - `"none"` will use the default behavior and have no permission
|
||
* - A list of routes can be provided that are relative to the file the worker
|
||
* is created in to limit the access of the worker (read/write permissions
|
||
* only)
|
||
*
|
||
* Example:
|
||
*
|
||
* ```ts
|
||
* // mod.ts
|
||
* const worker = new Worker(
|
||
* new URL("deno_worker.ts", import.meta.url).href, {
|
||
* type: "module",
|
||
* deno: {
|
||
* permissions: {
|
||
* read: true,
|
||
* },
|
||
* },
|
||
* }
|
||
* );
|
||
* ```
|
||
*/
|
||
deno?: {
|
||
/** Set to `"none"` to disable all the permissions in the worker. */
|
||
permissions?: Deno.PermissionOptions;
|
||
};
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Web Sockets
|
||
*/
|
||
declare interface WebSocketStreamOptions {
|
||
protocols?: string[];
|
||
signal?: AbortSignal;
|
||
headers?: HeadersInit;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Web Sockets
|
||
*/
|
||
declare interface WebSocketConnection {
|
||
readable: ReadableStream<string | Uint8Array>;
|
||
writable: WritableStream<string | Uint8Array>;
|
||
extensions: string;
|
||
protocol: string;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Web Sockets
|
||
*/
|
||
declare interface WebSocketCloseInfo {
|
||
code?: number;
|
||
reason?: string;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @tags allow-net
|
||
* @category Web Sockets
|
||
*/
|
||
declare class WebSocketStream {
|
||
constructor(url: string, options?: WebSocketStreamOptions);
|
||
url: string;
|
||
connection: Promise<WebSocketConnection>;
|
||
closed: Promise<WebSocketCloseInfo>;
|
||
close(closeInfo?: WebSocketCloseInfo): void;
|
||
}
|