2023-01-02 16:00:42 -05:00
|
|
|
|
// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
|
2020-04-30 11:23:40 -04:00
|
|
|
|
|
|
|
|
|
/// <reference no-default-lib="true" />
|
|
|
|
|
/// <reference lib="deno.ns" />
|
|
|
|
|
|
|
|
|
|
declare namespace Deno {
|
2022-07-04 01:41:52 -04:00
|
|
|
|
export {}; // stop default export type behavior
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2020-04-30 11:23:40 -04:00
|
|
|
|
*
|
|
|
|
|
* Retrieve the process umask. If `mask` is provided, sets the process umask.
|
|
|
|
|
* This call always returns what the umask was before the call.
|
|
|
|
|
*
|
2020-05-16 15:23:48 -04:00
|
|
|
|
* ```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)
|
|
|
|
|
* ```
|
2020-04-30 11:23:40 -04:00
|
|
|
|
*
|
2022-09-15 10:37:35 -04:00
|
|
|
|
* This API is under consideration to determine if permissions are required to
|
|
|
|
|
* call it.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* *Note*: This API is not implemented on Windows
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category File System
|
2020-04-30 11:23:40 -04:00
|
|
|
|
*/
|
|
|
|
|
export function umask(mask?: number): number;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* All plain number types for interfacing with foreign functions.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativeNumberType =
|
2021-08-06 17:28:10 -04:00
|
|
|
|
| "u8"
|
|
|
|
|
| "i8"
|
|
|
|
|
| "u16"
|
|
|
|
|
| "i16"
|
|
|
|
|
| "u32"
|
|
|
|
|
| "i32"
|
2022-06-20 22:50:33 -04:00
|
|
|
|
| "f32"
|
|
|
|
|
| "f64";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* All BigInt number types for interfacing with foreign functions.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativeBigIntType =
|
2021-08-06 17:28:10 -04:00
|
|
|
|
| "u64"
|
|
|
|
|
| "i64"
|
|
|
|
|
| "usize"
|
2022-06-20 22:50:33 -04:00
|
|
|
|
| "isize";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native boolean type for interfacing to foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-09-04 23:26:52 -04:00
|
|
|
|
type NativeBooleanType = "bool";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native pointer type for interfacing to foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativePointerType = "pointer";
|
2021-08-06 17:28:10 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native buffer type for interfacing to foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-08-22 23:46:43 -04:00
|
|
|
|
type NativeBufferType = "buffer";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native function type for interfacing with foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativeFunctionType = "function";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native void type for interfacing with foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativeVoidType = "void";
|
|
|
|
|
|
2023-01-07 22:58:10 -05:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2023-01-24 09:03:46 -05:00
|
|
|
|
*
|
2023-01-07 22:58:10 -05:00
|
|
|
|
* The native struct type for interfacing with foreign functions.
|
2023-01-24 09:03:46 -05:00
|
|
|
|
*
|
2023-01-07 22:58:10 -05:00
|
|
|
|
*/
|
|
|
|
|
type NativeStructType = { readonly struct: readonly NativeType[] };
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* All supported types for interfacing with foreign functions.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
export type NativeType =
|
|
|
|
|
| NativeNumberType
|
|
|
|
|
| NativeBigIntType
|
2022-09-04 23:26:52 -04:00
|
|
|
|
| NativeBooleanType
|
2022-06-20 22:50:33 -04:00
|
|
|
|
| NativePointerType
|
2022-08-22 23:46:43 -04:00
|
|
|
|
| NativeBufferType
|
2023-01-07 22:58:10 -05:00
|
|
|
|
| NativeFunctionType
|
|
|
|
|
| NativeStructType;
|
2022-06-20 22:50:33 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
export type NativeResultType = NativeType | NativeVoidType;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* A utility type conversion for foreign symbol parameters and unsafe callback
|
|
|
|
|
* return types.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-27 08:41:58 -04:00
|
|
|
|
type ToNativeTypeMap =
|
|
|
|
|
& Record<NativeNumberType, number>
|
2022-07-24 06:41:11 -04:00
|
|
|
|
& Record<NativeBigIntType, PointerValue>
|
2022-09-04 23:26:52 -04:00
|
|
|
|
& Record<NativeBooleanType, boolean>
|
2022-08-22 23:46:43 -04:00
|
|
|
|
& Record<NativePointerType, PointerValue | null>
|
|
|
|
|
& Record<NativeFunctionType, PointerValue | null>
|
2022-10-20 23:46:57 -04:00
|
|
|
|
& Record<NativeBufferType, BufferSource | null>;
|
2022-06-27 08:41:58 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Type conversion for foreign symbol parameters and unsafe callback return
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* types.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2023-01-07 22:58:10 -05:00
|
|
|
|
type ToNativeType<T extends NativeType = NativeType> = T extends
|
|
|
|
|
NativeStructType ? BufferSource
|
|
|
|
|
: ToNativeTypeMap[Exclude<T, NativeStructType>];
|
2022-06-27 08:41:58 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* A utility type for conversion for unsafe callback return types.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-27 08:41:58 -04:00
|
|
|
|
type ToNativeResultTypeMap = ToNativeTypeMap & Record<NativeVoidType, void>;
|
2022-06-20 22:50:33 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Type conversion for unsafe callback return types.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type ToNativeResultType<T extends NativeResultType = NativeResultType> =
|
2023-01-07 22:58:10 -05:00
|
|
|
|
T extends NativeStructType ? BufferSource
|
|
|
|
|
: ToNativeResultTypeMap[Exclude<T, NativeStructType>];
|
2022-06-27 08:41:58 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* A utility type for conversion of parameter types of foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-27 08:41:58 -04:00
|
|
|
|
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]>;
|
|
|
|
|
}
|
2022-06-20 22:50:33 -04:00
|
|
|
|
: never;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* A utility type for conversion of foreign symbol return types and unsafe
|
|
|
|
|
* callback parameters.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-27 08:41:58 -04:00
|
|
|
|
type FromNativeTypeMap =
|
|
|
|
|
& Record<NativeNumberType, number>
|
2022-07-24 06:41:11 -04:00
|
|
|
|
& Record<NativeBigIntType, PointerValue>
|
2022-09-04 23:26:52 -04:00
|
|
|
|
& Record<NativeBooleanType, boolean>
|
2022-07-24 06:41:11 -04:00
|
|
|
|
& Record<NativePointerType, PointerValue>
|
2022-08-22 23:46:43 -04:00
|
|
|
|
& Record<NativeBufferType, PointerValue>
|
2022-07-24 06:41:11 -04:00
|
|
|
|
& Record<NativeFunctionType, PointerValue>;
|
2022-06-20 22:50:33 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Type conversion for foreign symbol return types and unsafe callback
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* parameters.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2023-01-07 22:58:10 -05:00
|
|
|
|
type FromNativeType<T extends NativeType = NativeType> = T extends
|
|
|
|
|
NativeStructType ? Uint8Array
|
|
|
|
|
: FromNativeTypeMap[Exclude<T, NativeStructType>];
|
2022-06-27 08:41:58 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* A utility type for conversion for foreign symbol return types.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-27 08:41:58 -04:00
|
|
|
|
type FromNativeResultTypeMap =
|
|
|
|
|
& FromNativeTypeMap
|
|
|
|
|
& Record<NativeVoidType, void>;
|
2022-06-20 22:50:33 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Type conversion for foreign symbol return types.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type FromNativeResultType<T extends NativeResultType = NativeResultType> =
|
2023-01-07 22:58:10 -05:00
|
|
|
|
T extends NativeStructType ? Uint8Array
|
|
|
|
|
: FromNativeResultTypeMap[Exclude<T, NativeStructType>];
|
2022-06-27 08:41:58 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-27 08:41:58 -04:00
|
|
|
|
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]>;
|
|
|
|
|
}
|
2022-06-20 22:50:33 -04:00
|
|
|
|
: never;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* The interface for a foreign function as defined by its parameter and result
|
|
|
|
|
* types.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-01-10 10:33:25 -05:00
|
|
|
|
export interface ForeignFunction<
|
2022-06-20 22:50:33 -04:00
|
|
|
|
Parameters extends readonly NativeType[] = readonly NativeType[],
|
|
|
|
|
Result extends NativeResultType = NativeResultType,
|
2022-01-10 10:33:25 -05:00
|
|
|
|
NonBlocking extends boolean = boolean,
|
|
|
|
|
> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Name of the symbol.
|
|
|
|
|
*
|
|
|
|
|
* Defaults to the key name in symbols object. */
|
2022-01-11 01:21:16 -05:00
|
|
|
|
name?: string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The parameters of the foreign function. */
|
2022-01-10 10:33:25 -05:00
|
|
|
|
parameters: Parameters;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The result (return value) of the foreign function. */
|
2022-01-10 10:33:25 -05:00
|
|
|
|
result: Result;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** When `true`, function calls will run on a dedicated blocking thread and
|
|
|
|
|
* will return a `Promise` resolving to the `result`. */
|
2022-01-10 10:33:25 -05:00
|
|
|
|
nonblocking?: NonBlocking;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** When `true`, function calls can safely callback into JavaScript or
|
|
|
|
|
* trigger a garbage collection event.
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @default {false} */
|
2022-07-09 09:11:07 -04:00
|
|
|
|
callback?: boolean;
|
2021-08-06 17:28:10 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
export interface ForeignStatic<Type extends NativeType = NativeType> {
|
|
|
|
|
/** Name of the symbol, defaults to the key name in symbols object. */
|
|
|
|
|
name?: string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The type of the foreign static value. */
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type: Type;
|
2022-02-18 07:21:19 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A foreign library interface descriptor.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
export interface ForeignLibraryInterface {
|
|
|
|
|
[name: string]: ForeignFunction | ForeignStatic;
|
2022-01-10 10:33:25 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* A utility type that infers a foreign symbol.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
type StaticForeignSymbol<T extends ForeignFunction | ForeignStatic> =
|
2022-06-20 22:50:33 -04:00
|
|
|
|
T extends ForeignFunction ? FromForeignFunction<T>
|
|
|
|
|
: T extends ForeignStatic ? FromNativeType<T["type"]>
|
2022-02-18 07:21:19 -05:00
|
|
|
|
: never;
|
2022-01-10 10:33:25 -05:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type FromForeignFunction<T extends ForeignFunction> = T["parameters"] extends
|
|
|
|
|
readonly [] ? () => StaticForeignSymbolReturnType<T>
|
|
|
|
|
: (
|
|
|
|
|
...args: ToNativeParameterTypes<T["parameters"]>
|
|
|
|
|
) => StaticForeignSymbolReturnType<T>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type StaticForeignSymbolReturnType<T extends ForeignFunction> =
|
|
|
|
|
ConditionalAsync<T["nonblocking"], FromNativeResultType<T["result"]>>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-01-10 10:33:25 -05:00
|
|
|
|
type ConditionalAsync<IsAsync extends boolean | undefined, T> =
|
|
|
|
|
IsAsync extends true ? Promise<T> : T;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* A utility type that infers a foreign library interface.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
type StaticForeignLibraryInterface<T extends ForeignLibraryInterface> = {
|
|
|
|
|
[K in keyof T]: StaticForeignSymbol<T[K]>;
|
2022-01-10 10:33:25 -05:00
|
|
|
|
};
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-07-24 06:41:11 -04:00
|
|
|
|
* Pointer type depends on the architecture and actual pointer value.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2022-07-24 06:41:11 -04:00
|
|
|
|
*/
|
|
|
|
|
export type PointerValue = number | bigint;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* An unsafe pointer to a memory location for passing and returning pointers
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* to and from the FFI.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2021-12-15 09:41:49 -05:00
|
|
|
|
*/
|
|
|
|
|
export class UnsafePointer {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Return the direct memory pointer to the typed array in memory. */
|
2022-10-20 23:46:57 -04:00
|
|
|
|
static of(value: Deno.UnsafeCallback | BufferSource): PointerValue;
|
2021-12-15 09:41:49 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* An unsafe pointer view to a memory location as specified by the `pointer`
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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).
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2021-12-15 09:41:49 -05:00
|
|
|
|
*/
|
|
|
|
|
export class UnsafePointerView {
|
2022-10-21 07:54:01 -04:00
|
|
|
|
constructor(pointer: PointerValue);
|
2021-12-15 09:41:49 -05:00
|
|
|
|
|
2022-10-21 07:54:01 -04:00
|
|
|
|
pointer: PointerValue;
|
2021-12-15 09:41:49 -05:00
|
|
|
|
|
2022-09-04 23:26:52 -04:00
|
|
|
|
/** Gets a boolean at the specified byte offset from the pointer. */
|
|
|
|
|
getBool(offset?: number): boolean;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an unsigned 8-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getUint8(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 8-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getInt8(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an unsigned 16-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getUint16(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 16-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getInt16(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an unsigned 32-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getUint32(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 32-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getInt32(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an unsigned 64-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2022-07-24 06:41:11 -04:00
|
|
|
|
getBigUint64(offset?: number): PointerValue;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 64-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2022-07-24 06:41:11 -04:00
|
|
|
|
getBigInt64(offset?: number): PointerValue;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 32-bit float at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getFloat32(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 64-bit float at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getFloat64(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a C string (`null` terminated string) at the specified byte offset
|
|
|
|
|
* from the pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getCString(offset?: number): string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a C string (`null` terminated string) at the specified byte offset
|
|
|
|
|
* from the specified pointer. */
|
2022-09-01 13:31:05 -04:00
|
|
|
|
static getCString(pointer: PointerValue, offset?: number): string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
|
|
|
|
|
* offset from the pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
|
|
|
|
|
* offset from the specified pointer. */
|
2022-08-05 12:27:12 -04:00
|
|
|
|
static getArrayBuffer(
|
2022-09-01 13:31:05 -04:00
|
|
|
|
pointer: PointerValue,
|
2022-08-05 12:27:12 -04:00
|
|
|
|
byteLength: number,
|
|
|
|
|
offset?: number,
|
|
|
|
|
): ArrayBuffer;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** 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. */
|
2022-10-20 23:46:57 -04:00
|
|
|
|
copyInto(destination: BufferSource, offset?: number): void;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** 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. */
|
2022-08-05 12:27:12 -04:00
|
|
|
|
static copyInto(
|
2022-09-01 13:31:05 -04:00
|
|
|
|
pointer: PointerValue,
|
2022-10-20 23:46:57 -04:00
|
|
|
|
destination: BufferSource,
|
2022-08-05 12:27:12 -04:00
|
|
|
|
offset?: number,
|
|
|
|
|
): void;
|
2021-12-15 09:41:49 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* An unsafe pointer to a function, for calling functions that are not present
|
|
|
|
|
* as symbols.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2022-01-12 06:38:26 -05:00
|
|
|
|
*/
|
|
|
|
|
export class UnsafeFnPointer<Fn extends ForeignFunction> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The pointer to the function. */
|
2022-10-21 07:54:01 -04:00
|
|
|
|
pointer: PointerValue;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The definition of the function. */
|
2022-01-12 06:38:26 -05:00
|
|
|
|
definition: Fn;
|
|
|
|
|
|
2022-12-03 07:15:35 -05:00
|
|
|
|
constructor(pointer: PointerValue, definition: Const<Fn>);
|
2022-01-12 06:38:26 -05:00
|
|
|
|
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Call the foreign function. */
|
2022-06-20 22:50:33 -04:00
|
|
|
|
call: FromForeignFunction<Fn>;
|
2022-01-12 06:38:26 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Definition of a unsafe callback function.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 07:06:04 -04:00
|
|
|
|
export interface UnsafeCallbackDefinition<
|
|
|
|
|
Parameters extends readonly NativeType[] = readonly NativeType[],
|
2022-06-20 22:50:33 -04:00
|
|
|
|
Result extends NativeResultType = NativeResultType,
|
2022-06-20 07:06:04 -04:00
|
|
|
|
> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The parameters of the callbacks. */
|
2022-06-20 07:06:04 -04:00
|
|
|
|
parameters: Parameters;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The current result of the callback. */
|
2022-06-20 07:06:04 -04:00
|
|
|
|
result: Result;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* An unsafe callback function.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 07:06:04 -04:00
|
|
|
|
type UnsafeCallbackFunction<
|
|
|
|
|
Parameters extends readonly NativeType[] = readonly NativeType[],
|
2022-06-20 22:50:33 -04:00
|
|
|
|
Result extends NativeResultType = NativeResultType,
|
|
|
|
|
> = Parameters extends readonly [] ? () => ToNativeResultType<Result> : (
|
|
|
|
|
...args: FromNativeParameterTypes<Parameters>
|
|
|
|
|
) => ToNativeResultType<Result>;
|
2022-06-20 07:06:04 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* An unsafe function pointer for passing JavaScript functions as C function
|
|
|
|
|
* pointers to foreign function calls.
|
2022-06-20 07:06:04 -04:00
|
|
|
|
*
|
|
|
|
|
* The function pointer remains valid until the `close()` method is called.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* The callback can be explicitly referenced via `ref()` and dereferenced via
|
|
|
|
|
* `deref()` to stop Deno's process from exiting.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2022-06-20 07:06:04 -04:00
|
|
|
|
*/
|
|
|
|
|
export class UnsafeCallback<
|
2022-06-20 22:50:33 -04:00
|
|
|
|
Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition,
|
2022-06-20 07:06:04 -04:00
|
|
|
|
> {
|
|
|
|
|
constructor(
|
2022-12-03 07:15:35 -05:00
|
|
|
|
definition: Const<Definition>,
|
2022-06-20 22:50:33 -04:00
|
|
|
|
callback: UnsafeCallbackFunction<
|
|
|
|
|
Definition["parameters"],
|
|
|
|
|
Definition["result"]
|
|
|
|
|
>,
|
2022-06-20 07:06:04 -04:00
|
|
|
|
);
|
|
|
|
|
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The pointer to the unsafe callback. */
|
2022-10-21 07:54:01 -04:00
|
|
|
|
pointer: PointerValue;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The definition of the unsafe callback. */
|
2022-06-20 22:50:33 -04:00
|
|
|
|
definition: Definition;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The callback function. */
|
2022-06-20 22:50:33 -04:00
|
|
|
|
callback: UnsafeCallbackFunction<
|
|
|
|
|
Definition["parameters"],
|
|
|
|
|
Definition["result"]
|
|
|
|
|
>;
|
2022-06-20 07:06:04 -04:00
|
|
|
|
|
2022-06-28 05:23:36 -04:00
|
|
|
|
/**
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Adds one to this callback's reference counting and returns the new
|
|
|
|
|
* reference count.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* If the callback's reference count is non-zero, it will keep Deno's
|
|
|
|
|
* process from exiting.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*/
|
2022-10-15 09:49:46 -04:00
|
|
|
|
ref(): number;
|
2022-06-28 05:23:36 -04:00
|
|
|
|
|
|
|
|
|
/**
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Removes one from this callback's reference counting and returns the new
|
|
|
|
|
* reference count.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* If the callback's reference counter is zero, it will no longer keep
|
|
|
|
|
* Deno's process from exiting.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*/
|
2022-10-15 09:49:46 -04:00
|
|
|
|
unref(): number;
|
2022-06-28 05:23:36 -04:00
|
|
|
|
|
|
|
|
|
/**
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Removes the C function pointer associated with this instance.
|
|
|
|
|
*
|
|
|
|
|
* Continuing to use the instance after calling this object will lead to
|
|
|
|
|
* errors and crashes.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*
|
|
|
|
|
* 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.
|
|
|
|
|
*/
|
2022-06-20 07:06:04 -04:00
|
|
|
|
close(): void;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic
|
|
|
|
|
* library and return this interface.
|
2022-09-07 20:47:47 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
export interface DynamicLibrary<S extends ForeignLibraryInterface> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** All of the registered library along with functions for calling them. */
|
2022-02-18 07:21:19 -05:00
|
|
|
|
symbols: StaticForeignLibraryInterface<S>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** 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.
|
|
|
|
|
*/
|
2021-08-06 17:28:10 -04:00
|
|
|
|
close(): void;
|
|
|
|
|
}
|
|
|
|
|
|
2022-12-03 07:15:35 -05:00
|
|
|
|
/**
|
|
|
|
|
* 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]> }
|
|
|
|
|
| []
|
|
|
|
|
>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example Given a C library which exports a foreign function named `add()`
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* ```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
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category FFI
|
2021-07-11 21:12:26 -04:00
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
export function dlopen<S extends ForeignLibraryInterface>(
|
2021-08-24 09:09:00 -04:00
|
|
|
|
filename: string | URL,
|
2022-12-03 07:15:35 -05:00
|
|
|
|
symbols: Const<S>,
|
2021-08-06 17:28:10 -04:00
|
|
|
|
): DynamicLibrary<S>;
|
2021-07-11 21:12:26 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* These are unstable options which can be used with {@linkcode Deno.run}.
|
2022-11-13 17:27:47 -05:00
|
|
|
|
*
|
|
|
|
|
* @category Sub Process
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*/
|
|
|
|
|
interface UnstableRunOptions extends RunOptions {
|
|
|
|
|
/** If `true`, clears the environment variables before executing the
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* sub-process.
|
|
|
|
|
*
|
|
|
|
|
* @default {false} */
|
2022-10-26 09:53:48 -04:00
|
|
|
|
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
|
2022-09-15 10:37:35 -04:00
|
|
|
|
* @category Sub Process
|
|
|
|
|
*/
|
2022-10-26 09:53:48 -04:00
|
|
|
|
export function run<T extends UnstableRunOptions = UnstableRunOptions>(
|
|
|
|
|
opt: T,
|
|
|
|
|
): Process<T>;
|
2021-08-04 15:47:43 -04:00
|
|
|
|
|
2022-09-15 08:09:23 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* A custom `HttpClient` for use with {@linkcode fetch} function. This is
|
|
|
|
|
* designed to allow custom certificates or proxies to be used with `fetch()`.
|
2020-08-10 16:41:51 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example ```ts
|
2021-09-30 03:26:15 -04:00
|
|
|
|
* const caCert = await Deno.readTextFile("./ca.pem");
|
|
|
|
|
* const client = Deno.createHttpClient({ caCerts: [ caCert ] });
|
2020-08-05 14:44:03 -04:00
|
|
|
|
* const req = await fetch("https://myserver.com", { client });
|
|
|
|
|
* ```
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
2020-08-05 14:44:03 -04:00
|
|
|
|
*/
|
2022-10-26 09:53:48 -04:00
|
|
|
|
export interface HttpClient {
|
|
|
|
|
/** The resource ID associated with the client. */
|
2020-08-05 14:44:03 -04:00
|
|
|
|
rid: number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Close the HTTP client. */
|
2020-08-05 14:44:03 -04:00
|
|
|
|
close(): void;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 08:09:23 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* The options used when creating a {@linkcode Deno.HttpClient}.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
2020-08-05 14:44:03 -04:00
|
|
|
|
*/
|
2021-04-09 20:41:59 -04:00
|
|
|
|
export interface CreateHttpClientOptions {
|
2021-09-30 03:26:15 -04:00
|
|
|
|
/** 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. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
proxy?: Proxy;
|
2021-09-30 03:26:15 -04:00
|
|
|
|
/** PEM formatted client certificate chain. */
|
2021-08-25 08:25:12 -04:00
|
|
|
|
certChain?: string;
|
2021-09-30 03:26:15 -04:00
|
|
|
|
/** PEM formatted (RSA or PKCS8) private key of client certificate. */
|
2021-08-25 08:25:12 -04:00
|
|
|
|
privateKey?: string;
|
2021-06-21 23:21:57 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The definition of a proxy when specifying
|
|
|
|
|
* {@linkcode Deno.CreateHttpClientOptions}.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
|
|
|
|
*/
|
2021-06-21 23:21:57 -04:00
|
|
|
|
export interface Proxy {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The string URL of the proxy server to use. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
url: string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The basic auth credentials to be used against the proxy server. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
basicAuth?: BasicAuth;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Basic authentication credentials to be used with a {@linkcode Deno.Proxy}
|
|
|
|
|
* server when specifying {@linkcode Deno.CreateHttpClientOptions}.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
|
|
|
|
*/
|
2021-06-21 23:21:57 -04:00
|
|
|
|
export interface BasicAuth {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The username to be used against the proxy server. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
username: string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The password to be used against the proxy server. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
password: string;
|
2020-08-05 14:44:03 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 08:09:23 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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()`.
|
2020-08-10 16:41:51 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example ```ts
|
2021-09-30 03:26:15 -04:00
|
|
|
|
* const caCert = await Deno.readTextFile("./ca.pem");
|
|
|
|
|
* const client = Deno.createHttpClient({ caCerts: [ caCert ] });
|
2021-06-21 23:21:57 -04:00
|
|
|
|
* const response = await fetch("https://myserver.com", { client });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example ```ts
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* const client = Deno.createHttpClient({
|
|
|
|
|
* proxy: { url: "http://myproxy.com:8080" }
|
|
|
|
|
* });
|
2021-06-21 23:21:57 -04:00
|
|
|
|
* const response = await fetch("https://myserver.com", { client });
|
2020-08-05 14:44:03 -04:00
|
|
|
|
* ```
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
2020-08-05 14:44:03 -04:00
|
|
|
|
*/
|
|
|
|
|
export function createHttpClient(
|
|
|
|
|
options: CreateHttpClientOptions,
|
|
|
|
|
): HttpClient;
|
2020-08-31 14:29:43 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* A generic transport listener for message-oriented protocols.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** 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.
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Sends a message to the target via the connection. The method resolves
|
|
|
|
|
* with the number of bytes sent. */
|
2021-08-31 05:25:15 -04:00
|
|
|
|
send(p: Uint8Array, addr: Addr): Promise<number>;
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** Close closes the socket. Any pending message promises will be rejected
|
2021-08-31 05:25:15 -04:00
|
|
|
|
* with errors. */
|
|
|
|
|
close(): void;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Return the address of the instance. */
|
2021-08-31 05:25:15 -04:00
|
|
|
|
readonly addr: Addr;
|
|
|
|
|
[Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>;
|
|
|
|
|
}
|
|
|
|
|
|
2022-10-26 15:04:27 -04:00
|
|
|
|
/**
|
|
|
|
|
* @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
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* platforms.
|
|
|
|
|
*
|
|
|
|
|
* @default {false} */
|
2022-10-26 15:04:27 -04:00
|
|
|
|
reusePort?: boolean;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Unstable options which can be set when opening a Unix listener via
|
|
|
|
|
* {@linkcode Deno.listen} or {@linkcode Deno.listenDatagram}.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export interface UnixListenOptions {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** A path to the Unix Socket. */
|
2021-08-31 05:25:15 -04:00
|
|
|
|
path: string;
|
|
|
|
|
}
|
|
|
|
|
|
2022-10-24 05:05:07 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Unstable options which can be set when opening a datagram listener via
|
|
|
|
|
* {@linkcode Deno.listenDatagram}.
|
2022-10-24 05:05:07 -04:00
|
|
|
|
*
|
|
|
|
|
* @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
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* socket from the listener.
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @default {false} */
|
2022-10-24 05:05:07 -04:00
|
|
|
|
reuseAddress?: boolean;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2021-08-31 05:25:15 -04:00
|
|
|
|
* Listen announces on the local transport address.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const listener = Deno.listen({ path: "/foo/bar.sock", transport: "unix" })
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* Requires `allow-read` and `allow-write` permission.
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-read, allow-write
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export function listen(
|
|
|
|
|
options: UnixListenOptions & { transport: "unix" },
|
|
|
|
|
): Listener;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Listen announces on the local transport address.
|
2021-08-31 05:25:15 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const listener1 = Deno.listenDatagram({
|
|
|
|
|
* port: 80,
|
|
|
|
|
* transport: "udp"
|
|
|
|
|
* });
|
|
|
|
|
* const listener2 = Deno.listenDatagram({
|
|
|
|
|
* hostname: "golang.org",
|
|
|
|
|
* port: 80,
|
|
|
|
|
* transport: "udp"
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* Requires `allow-net` permission.
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-net
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export function listenDatagram(
|
2022-10-24 05:05:07 -04:00
|
|
|
|
options: UdpListenOptions & { transport: "udp" },
|
2021-08-31 05:25:15 -04:00
|
|
|
|
): DatagramConn;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Listen announces on the local transport address.
|
2021-08-31 05:25:15 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const listener = Deno.listenDatagram({
|
|
|
|
|
* path: "/foo/bar.sock",
|
|
|
|
|
* transport: "unixpacket"
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* Requires `allow-read` and `allow-write` permission.
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-read, allow-write
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export function listenDatagram(
|
|
|
|
|
options: UnixListenOptions & { transport: "unixpacket" },
|
|
|
|
|
): DatagramConn;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export interface UnixConnectOptions {
|
|
|
|
|
transport: "unix";
|
|
|
|
|
path: string;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2021-08-31 05:25:15 -04:00
|
|
|
|
*
|
|
|
|
|
* 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" });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* Requires `allow-net` permission for "tcp" and `allow-read` for "unix".
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-net, allow-read
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2022-10-26 09:53:48 -04:00
|
|
|
|
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>;
|
2021-08-31 05:25:15 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-09-30 03:26:15 -04:00
|
|
|
|
export interface ConnectTlsOptions {
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* PEM formatted client certificate chain.
|
|
|
|
|
*/
|
2021-09-30 03:26:15 -04:00
|
|
|
|
certChain?: string;
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* PEM formatted (RSA or PKCS8) private key of client certificate.
|
|
|
|
|
*/
|
2021-09-30 03:26:15 -04:00
|
|
|
|
privateKey?: string;
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Application-Layer Protocol Negotiation (ALPN) protocols supported by
|
2021-11-26 13:59:53 -05:00
|
|
|
|
* the client. If not specified, no ALPN extension will be included in the
|
|
|
|
|
* TLS handshake.
|
|
|
|
|
*/
|
|
|
|
|
alpnProtocols?: string[];
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-11-26 13:59:53 -05:00
|
|
|
|
export interface TlsHandshakeInfo {
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Contains the ALPN protocol selected during negotiation with the server.
|
2021-11-26 13:59:53 -05:00
|
|
|
|
* If no ALPN protocol selected, returns `null`.
|
|
|
|
|
*/
|
|
|
|
|
alpnProtocol: string | null;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-11-26 13:59:53 -05:00
|
|
|
|
export interface TlsConn extends Conn {
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Runs the client or server handshake protocol to completion if that has
|
2021-11-26 13:59:53 -05:00
|
|
|
|
* not happened yet. Calling this method is optional; the TLS handshake
|
2022-09-15 10:37:35 -04:00
|
|
|
|
* will be completed automatically as soon as data is sent or received.
|
|
|
|
|
*/
|
2021-11-26 13:59:53 -05:00
|
|
|
|
handshake(): Promise<TlsHandshakeInfo>;
|
2021-08-31 05:25:15 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Create a TLS connection with an attached client certificate.
|
2021-09-02 18:28:12 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const conn = await Deno.connectTls({
|
|
|
|
|
* hostname: "deno.land",
|
|
|
|
|
* port: 443,
|
|
|
|
|
* certChain: "---- BEGIN CERTIFICATE ----\n ...",
|
|
|
|
|
* privateKey: "---- BEGIN PRIVATE KEY ----\n ...",
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* Requires `allow-net` permission.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-net
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category Network
|
2021-09-02 18:28:12 -04:00
|
|
|
|
*/
|
2021-10-26 16:27:47 -04:00
|
|
|
|
export function connectTls(options: ConnectTlsOptions): Promise<TlsConn>;
|
2021-08-31 05:25:15 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export interface ListenTlsOptions {
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Application-Layer Protocol Negotiation (ALPN) protocols to announce to
|
2021-08-31 05:25:15 -04:00
|
|
|
|
* the client. If not specified, no ALPN extension will be included in the
|
|
|
|
|
* TLS handshake.
|
|
|
|
|
*/
|
|
|
|
|
alpnProtocols?: string[];
|
|
|
|
|
}
|
2021-09-19 08:46:54 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-11-26 13:59:53 -05:00
|
|
|
|
export interface StartTlsOptions {
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Application-Layer Protocol Negotiation (ALPN) protocols to announce to
|
2021-11-26 13:59:53 -05:00
|
|
|
|
* the client. If not specified, no ALPN extension will be included in the
|
|
|
|
|
* TLS handshake.
|
|
|
|
|
*/
|
|
|
|
|
alpnProtocols?: string[];
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* Acquire an advisory file-system lock for the provided file.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @param [exclusive=false]
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category File System
|
2021-09-19 08:46:54 -04:00
|
|
|
|
*/
|
|
|
|
|
export function flock(rid: number, exclusive?: boolean): Promise<void>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Acquire an advisory file-system lock synchronously for the provided file.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @param [exclusive=false]
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category File System
|
2021-09-19 08:46:54 -04:00
|
|
|
|
*/
|
|
|
|
|
export function flockSync(rid: number, exclusive?: boolean): void;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Release an advisory file-system lock for the provided file.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category File System
|
2021-09-19 08:46:54 -04:00
|
|
|
|
*/
|
|
|
|
|
export function funlock(rid: number): Promise<void>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Release an advisory file-system lock for the provided file synchronously.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category File System
|
2021-09-19 08:46:54 -04:00
|
|
|
|
*/
|
|
|
|
|
export function funlockSync(rid: number): void;
|
2021-12-09 03:00:55 -05:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* 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.
|
|
|
|
|
*
|
2022-08-18 08:05:02 -04:00
|
|
|
|
* @category HTTP Server
|
|
|
|
|
*/
|
2022-08-23 18:08:56 -04:00
|
|
|
|
export type ServeHandler = (request: Request) => Response | Promise<Response>;
|
2022-08-19 08:36:01 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Options which can be set when calling {@linkcode Deno.serve}.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* @category HTTP Server
|
|
|
|
|
*/
|
|
|
|
|
export interface ServeOptions extends Partial<Deno.ListenOptions> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** An {@linkcode AbortSignal} to close the server and all connections. */
|
2022-08-18 08:05:02 -04:00
|
|
|
|
signal?: AbortSignal;
|
|
|
|
|
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Sets `SO_REUSEPORT` on POSIX systems. */
|
2022-09-28 13:46:29 -04:00
|
|
|
|
reusePort?: boolean;
|
|
|
|
|
|
2022-08-18 08:05:02 -04:00
|
|
|
|
/** The handler to invoke when route handlers throw an error. */
|
|
|
|
|
onError?: (error: unknown) => Response | Promise<Response>;
|
|
|
|
|
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The callback which is called when the server starts listening. */
|
2022-08-18 08:05:02 -04:00
|
|
|
|
onListen?: (params: { hostname: string; port: number }) => void;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Additional options which are used when opening a TLS (HTTPS) server.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-08-18 08:05:02 -04:00
|
|
|
|
* @category HTTP Server
|
|
|
|
|
*/
|
2022-08-23 18:08:56 -04:00
|
|
|
|
export interface ServeTlsOptions extends ServeOptions {
|
2022-08-18 08:05:02 -04:00
|
|
|
|
/** Server private key in PEM format */
|
|
|
|
|
cert: string;
|
|
|
|
|
|
|
|
|
|
/** Cert chain in PEM format */
|
|
|
|
|
key: string;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* @category HTTP Server
|
|
|
|
|
*/
|
|
|
|
|
export interface ServeInit {
|
|
|
|
|
/** The handler to invoke to process each incoming request. */
|
|
|
|
|
handler: ServeHandler;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Serves HTTP requests with the given handler.
|
2022-08-18 08:05:02 -04:00
|
|
|
|
*
|
|
|
|
|
* You can specify an object with a port and hostname option, which is the
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
|
2022-08-18 08:05:02 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* The below example serves with the port `9000`.
|
2022-08-18 08:05:02 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* Deno.serve((_req) => new Response("Hello, world"));
|
2022-08-18 08:05:02 -04:00
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* You can change the address to listen on using the `hostname` and `port`
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* options. The below example serves on port `3000`.
|
2022-08-18 08:05:02 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
|
2022-08-19 08:36:01 -04:00
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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.
|
2022-08-19 08:36:01 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const ac = new AbortController();
|
|
|
|
|
*
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world"))
|
|
|
|
|
* .then(() => console.log("Server closed"));
|
2022-08-19 08:36:01 -04:00
|
|
|
|
*
|
|
|
|
|
* console.log("Closing server...");
|
|
|
|
|
* ac.abort();
|
2022-08-18 08:05:02 -04:00
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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.
|
2022-08-18 08:05:02 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2022-08-19 08:36:01 -04:00
|
|
|
|
* Deno.serve({
|
2022-08-18 08:05:02 -04:00
|
|
|
|
* onListen({ port, hostname }) {
|
|
|
|
|
* console.log(`Server started at http://${hostname}:${port}`);
|
|
|
|
|
* // ... more info specific to your server ..
|
|
|
|
|
* },
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* handler: (_req) => new Response("Hello, world"),
|
2022-08-18 08:05:02 -04:00
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* To enable TLS you must specify the `key` and `cert` options.
|
2022-08-18 08:05:02 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
|
|
|
|
|
* const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
|
2022-08-23 18:08:56 -04:00
|
|
|
|
* Deno.serve({ cert, key }, (_req) => new Response("Hello, world"));
|
2022-08-27 15:20:25 -04:00
|
|
|
|
* ```
|
2022-08-18 08:05:02 -04:00
|
|
|
|
*
|
|
|
|
|
* @category HTTP Server
|
|
|
|
|
*/
|
2022-08-19 08:36:01 -04:00
|
|
|
|
export function serve(
|
2022-08-23 18:08:56 -04:00
|
|
|
|
handler: ServeHandler,
|
|
|
|
|
options?: ServeOptions | ServeTlsOptions,
|
|
|
|
|
): Promise<void>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** **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
|
|
|
|
|
*/
|
2022-08-23 18:08:56 -04:00
|
|
|
|
export function serve(
|
|
|
|
|
options: ServeOptions | ServeTlsOptions,
|
|
|
|
|
handler: ServeHandler,
|
|
|
|
|
): Promise<void>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** **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
|
|
|
|
|
*/
|
2022-08-23 18:08:56 -04:00
|
|
|
|
export function serve(
|
|
|
|
|
options: ServeInit & (ServeOptions | ServeTlsOptions),
|
2022-08-18 08:05:02 -04:00
|
|
|
|
): Promise<void>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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}).
|
2022-03-16 09:54:18 -04:00
|
|
|
|
*
|
|
|
|
|
* 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.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-08-24 08:10:57 -04:00
|
|
|
|
* ```ts
|
|
|
|
|
* function handler(req: Request): Response {
|
|
|
|
|
* Deno.upgradeHttp(req).then(([conn, firstPacket]) => {
|
|
|
|
|
* // ...
|
|
|
|
|
* });
|
|
|
|
|
* return new Response(null, { status: 101 });
|
|
|
|
|
* }
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* This method can only be called on requests originating the
|
|
|
|
|
* {@linkcode Deno.serveHttp} server.
|
2022-08-24 08:10:57 -04:00
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category HTTP Server
|
2022-03-16 09:54:18 -04:00
|
|
|
|
*/
|
|
|
|
|
export function upgradeHttp(
|
|
|
|
|
request: Request,
|
2022-08-24 08:10:57 -04:00
|
|
|
|
): Promise<[Deno.Conn, Uint8Array]>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Allows "hijacking" the connection that the request is associated with.
|
2022-08-24 08:10:57 -04:00
|
|
|
|
* This can be used to implement protocols that build on top of HTTP (eg.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* {@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.
|
2022-08-24 08:10:57 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* This method can only be called on requests originating the
|
|
|
|
|
* {@linkcode Deno.serve} server.
|
2022-08-24 08:10:57 -04:00
|
|
|
|
*
|
|
|
|
|
* @category HTTP Server
|
|
|
|
|
*/
|
|
|
|
|
export function upgradeHttpRaw(request: Request): [Deno.Conn, Uint8Array];
|
2022-04-20 18:20:33 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-11-13 14:00:24 -05:00
|
|
|
|
*
|
|
|
|
|
* 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.
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example Spawn a subprocess and pipe the output to a file
|
|
|
|
|
*
|
2022-11-13 14:00:24 -05:00
|
|
|
|
* ```ts
|
|
|
|
|
* const command = new Deno.Command(Deno.execPath(), {
|
|
|
|
|
* args: [
|
|
|
|
|
* "eval",
|
|
|
|
|
* "console.log('Hello World')",
|
|
|
|
|
* ],
|
|
|
|
|
* stdin: "piped",
|
|
|
|
|
* });
|
2022-11-28 06:33:51 -05:00
|
|
|
|
* const child = command.spawn();
|
2022-11-13 14:00:24 -05:00
|
|
|
|
*
|
|
|
|
|
* // open a file and pipe the subprocess output to it.
|
2022-11-28 06:33:51 -05:00
|
|
|
|
* child.stdout.pipeTo(Deno.openSync("output").writable);
|
2022-11-13 14:00:24 -05:00
|
|
|
|
*
|
|
|
|
|
* // manually close stdin
|
2022-11-28 06:33:51 -05:00
|
|
|
|
* child.stdin.close();
|
|
|
|
|
* const status = await child.status;
|
2022-11-13 14:00:24 -05:00
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example Spawn a subprocess and collect its output
|
|
|
|
|
*
|
2022-11-13 14:00:24 -05:00
|
|
|
|
* ```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));
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example Spawn a subprocess and collect its output synchronously
|
|
|
|
|
*
|
2022-11-13 14:00:24 -05:00
|
|
|
|
* ```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.
|
|
|
|
|
*/
|
2022-11-28 06:33:51 -05:00
|
|
|
|
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>;
|
2022-11-13 14:00:24 -05:00
|
|
|
|
|
2022-11-28 06:33:51 -05:00
|
|
|
|
/** Waits for the child to exit completely, returning all its output and
|
|
|
|
|
* status. */
|
|
|
|
|
output(): Promise<CommandOutput>;
|
2022-12-13 08:14:41 -05:00
|
|
|
|
/** Kills the process with given {@linkcode Deno.Signal}.
|
|
|
|
|
*
|
|
|
|
|
* @param [signo="SIGTERM"]
|
|
|
|
|
*/
|
2022-11-13 14:00:24 -05:00
|
|
|
|
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. */
|
2023-02-10 12:09:02 -05:00
|
|
|
|
args?: readonly string[];
|
2022-11-13 14:00:24 -05:00
|
|
|
|
/**
|
|
|
|
|
* 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.
|
2022-12-13 08:14:41 -05:00
|
|
|
|
*
|
|
|
|
|
* @default {false}
|
2022-11-13 14:00:24 -05:00
|
|
|
|
*/
|
|
|
|
|
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.
|
|
|
|
|
*
|
2023-01-25 12:28:08 -05:00
|
|
|
|
* Not supported in {@linkcode Deno.Command.outputSync}.
|
2022-11-13 14:00:24 -05:00
|
|
|
|
*/
|
|
|
|
|
signal?: AbortSignal;
|
|
|
|
|
|
|
|
|
|
/** How `stdin` of the spawned process should be handled.
|
|
|
|
|
*
|
2023-01-24 09:03:46 -05:00
|
|
|
|
* Defaults to `"inherit"` for `output` & `outputSync`,
|
|
|
|
|
* and `"inherit"` for `spawn`. */
|
2022-11-13 14:00:24 -05:00
|
|
|
|
stdin?: "piped" | "inherit" | "null";
|
|
|
|
|
/** How `stdout` of the spawned process should be handled.
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* Defaults to `"piped"` for `output` & `outputSync`,
|
|
|
|
|
* and `"inherit"` for `spawn`. */
|
2022-11-13 14:00:24 -05:00
|
|
|
|
stdout?: "piped" | "inherit" | "null";
|
|
|
|
|
/** How `stderr` of the spawned process should be handled.
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* Defaults to `"piped"` for `output` & `outputSync`,
|
|
|
|
|
* and `"inherit"` for `spawn`. */
|
2022-11-13 14:00:24 -05:00
|
|
|
|
stderr?: "piped" | "inherit" | "null";
|
|
|
|
|
|
2022-12-13 08:14:41 -05:00
|
|
|
|
/** Skips quoting and escaping of the arguments on windows. This option
|
|
|
|
|
* is ignored on non-windows platforms.
|
|
|
|
|
*
|
|
|
|
|
* @default {false} */
|
2022-11-13 14:00:24 -05:00
|
|
|
|
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
|
|
|
|
|
*/
|
2022-11-18 09:20:07 -05:00
|
|
|
|
export interface CommandOutput extends CommandStatus {
|
2022-11-13 14:00:24 -05:00
|
|
|
|
/** The buffered output from the child process' `stdout`. */
|
|
|
|
|
readonly stdout: Uint8Array;
|
|
|
|
|
/** The buffered output from the child process' `stderr`. */
|
|
|
|
|
readonly stderr: Uint8Array;
|
|
|
|
|
}
|
2022-12-26 18:16:12 -05:00
|
|
|
|
|
|
|
|
|
/** **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;
|
2020-04-30 11:23:40 -04:00
|
|
|
|
}
|
2020-08-05 14:44:03 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* 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.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-net, allow-read
|
|
|
|
|
* @category Fetch API
|
|
|
|
|
*/
|
2020-08-05 14:44:03 -04:00
|
|
|
|
declare function fetch(
|
|
|
|
|
input: Request | URL | string,
|
|
|
|
|
init?: RequestInit & { client: Deno.HttpClient },
|
|
|
|
|
): Promise<Response>;
|
2021-01-29 08:15:59 -05:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Web Workers
|
|
|
|
|
*/
|
2021-01-29 08:15:59 -05:00
|
|
|
|
declare interface WorkerOptions {
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Configure permissions options to change the level of access the worker will
|
2022-03-24 11:27:24 -04:00
|
|
|
|
* have. By default it will have no permissions. Note that the permissions
|
2021-01-29 08:15:59 -05:00
|
|
|
|
* of a worker can't be extended beyond its parent's permissions reach.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* - `"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)
|
2021-01-29 08:15:59 -05:00
|
|
|
|
*
|
|
|
|
|
* Example:
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* // mod.ts
|
|
|
|
|
* const worker = new Worker(
|
|
|
|
|
* new URL("deno_worker.ts", import.meta.url).href, {
|
|
|
|
|
* type: "module",
|
|
|
|
|
* deno: {
|
|
|
|
|
* permissions: {
|
|
|
|
|
* read: true,
|
|
|
|
|
* },
|
|
|
|
|
* },
|
|
|
|
|
* }
|
|
|
|
|
* );
|
|
|
|
|
* ```
|
|
|
|
|
*/
|
2022-05-17 16:27:17 -04:00
|
|
|
|
deno?: {
|
2021-01-29 08:15:59 -05:00
|
|
|
|
/** Set to `"none"` to disable all the permissions in the worker. */
|
2022-03-10 19:35:33 -05:00
|
|
|
|
permissions?: Deno.PermissionOptions;
|
2021-01-29 08:15:59 -05:00
|
|
|
|
};
|
|
|
|
|
}
|
2021-08-09 18:28:17 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
2021-08-09 18:28:17 -04:00
|
|
|
|
declare interface WebSocketStreamOptions {
|
|
|
|
|
protocols?: string[];
|
|
|
|
|
signal?: AbortSignal;
|
2022-01-05 11:41:44 -05:00
|
|
|
|
headers?: HeadersInit;
|
2021-08-09 18:28:17 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
2021-08-09 18:28:17 -04:00
|
|
|
|
declare interface WebSocketConnection {
|
|
|
|
|
readable: ReadableStream<string | Uint8Array>;
|
|
|
|
|
writable: WritableStream<string | Uint8Array>;
|
|
|
|
|
extensions: string;
|
|
|
|
|
protocol: string;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
2021-08-09 18:28:17 -04:00
|
|
|
|
declare interface WebSocketCloseInfo {
|
|
|
|
|
code?: number;
|
|
|
|
|
reason?: string;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-net
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
2021-08-09 18:28:17 -04:00
|
|
|
|
declare class WebSocketStream {
|
|
|
|
|
constructor(url: string, options?: WebSocketStreamOptions);
|
|
|
|
|
url: string;
|
|
|
|
|
connection: Promise<WebSocketConnection>;
|
|
|
|
|
closed: Promise<WebSocketCloseInfo>;
|
|
|
|
|
close(closeInfo?: WebSocketCloseInfo): void;
|
|
|
|
|
}
|