mirror of https://github.com/grpc/grpc-node.git
1469 lines
48 KiB
TypeScript
1469 lines
48 KiB
TypeScript
declare module "grpc" {
|
|
import { Message, Service as ProtobufService } from "protobufjs";
|
|
import { Duplex, Readable, Writable } from "stream";
|
|
import { SecureContext } from "tls";
|
|
|
|
/**
|
|
* Load a ProtoBuf.js object as a gRPC object.
|
|
* @param value The ProtoBuf.js reflection object to load
|
|
* @param options Options to apply to the loaded file
|
|
* @return The resulting gRPC object.
|
|
*/
|
|
export function loadObject<T = GrpcObject>(value: object, options?: LoadObjectOptions): T;
|
|
|
|
/**
|
|
* Options for loading proto object as gRPC object
|
|
* @param {(number|string)=} [options.protobufjsVersion='detect'] 5 and 6
|
|
* respectively indicate that an object from the corresponding version of
|
|
* Protobuf.js is provided in the value argument. If the option is 'detect',
|
|
* gRPC will guess what the version is based on the structure of the value.
|
|
*/
|
|
export interface LoadObjectOptions {
|
|
/**
|
|
* Deserialize bytes values as base64 strings instead of Buffers.
|
|
* Defaults to `false`.
|
|
*/
|
|
binaryAsBase64?: boolean;
|
|
|
|
/**
|
|
* Deserialize long values as strings instead of objects.
|
|
* Defaults to `true`.
|
|
*/
|
|
longsAsStrings?: boolean;
|
|
|
|
/**
|
|
* Deserialize enum values as strings instead of numbers. Only works with
|
|
* Protobuf.js 6 values.
|
|
* Defaults to `true`.
|
|
*/
|
|
enumsAsStrings?: boolean;
|
|
|
|
/**
|
|
* use the beta method argument order for client methods, with optional
|
|
* arguments after the callback. This option is only a temporary stopgap
|
|
* measure to smooth an API breakage. It is deprecated, and new code
|
|
* should not use it.
|
|
* Defaults to `false`
|
|
*/
|
|
deprecatedArgumentOrder?: boolean;
|
|
|
|
/**
|
|
* 5 and 6 respectively indicate that an object from the corresponding
|
|
* version of Protobuf.js is provided in the value argument. If the option
|
|
* is 'detect', gRPC wll guess what the version is based on the structure
|
|
* of the value.
|
|
*/
|
|
protobufjsVersion?: 5 | 6 | "detect";
|
|
}
|
|
|
|
/**
|
|
* Map from `.proto` file.
|
|
* - Namespaces become maps from the names of their direct members to those member objects
|
|
* - Service definitions become client constructors for clients for that service. They also
|
|
* have a service member that can be used for constructing servers.
|
|
* - Message definitions become Message constructors like those that ProtoBuf.js would create
|
|
* - Enum definitions become Enum objects like those that ProtoBuf.js would create
|
|
* - Anything else becomes the relevant reflection object that ProtoBuf.js would create
|
|
*/
|
|
export interface GrpcObject {
|
|
[name: string]: GrpcObject | typeof Client | Message<any>;
|
|
}
|
|
|
|
/**
|
|
* Load a gRPC object from a .proto file.
|
|
* @param filename The file to load
|
|
* @param format The file format to expect. Defaults to 'proto'
|
|
* @param options Options to apply to the loaded file
|
|
* @return The resulting gRPC object
|
|
*/
|
|
export function load<T = GrpcObject>(filename: Filename, format?: "proto" | "json", options?: LoadOptions): T;
|
|
|
|
/**
|
|
* Load a gRPC package definition as a gRPC object hierarchy
|
|
* @param packageDef The package definition object
|
|
* @return The resulting gRPC object
|
|
*/
|
|
export function loadPackageDefinition(packageDefinition: PackageDefinition): GrpcObject;
|
|
|
|
/**
|
|
* A filename
|
|
*/
|
|
export type Filename = string | { root: string, file: string };
|
|
|
|
/**
|
|
* Options for loading proto file as gRPC object
|
|
*/
|
|
export interface LoadOptions {
|
|
/**
|
|
* Load this file with field names in camel case instead of their original case.
|
|
* Defaults to `false`.
|
|
*/
|
|
convertFieldsToCamelCase?: boolean;
|
|
|
|
/**
|
|
* Deserialize bytes values as base64 strings instead of Buffers.
|
|
* Defaults to `false`.
|
|
*/
|
|
binaryAsBase64?: boolean;
|
|
|
|
/**
|
|
* Deserialize long values as strings instead of objects.
|
|
* Defaults to `true`.
|
|
*/
|
|
longsAsStrings?: boolean;
|
|
|
|
/**
|
|
* Use the beta method argument order for client methods, with optional
|
|
* arguments after the callback. This option is only a temporary stopgap
|
|
* measure to smooth an API breakage. It is deprecated, and new code
|
|
* should not use it.
|
|
* Defaults to `false`
|
|
*/
|
|
deprecatedArgumentOrder?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Sets the logger function for the gRPC module. For debugging purposes, the C
|
|
* core will log synchronously directly to stdout unless this function is
|
|
* called. Note: the output format here is intended to be informational, and
|
|
* is not guaranteed to stay the same in the future.
|
|
* Logs will be directed to logger.error.
|
|
* @param logger A Console-like object.
|
|
*/
|
|
export function setLogger(logger: Console): void;
|
|
|
|
/**
|
|
* Sets the logger verbosity for gRPC module logging. The options are members
|
|
* of the grpc.logVerbosity map.
|
|
* @param verbosity The minimum severity to log
|
|
*/
|
|
export function setLogVerbosity(verbosity: logVerbosity): void;
|
|
|
|
/**
|
|
* Server object that stores request handlers and delegates incoming requests to those handlers
|
|
*/
|
|
export class Server {
|
|
/**
|
|
* Constructs a server object that stores request handlers and delegates
|
|
* incoming requests to those handlers
|
|
* @param options Options that should be passed to the internal server
|
|
* implementation
|
|
* ```
|
|
* var server = new grpc.Server();
|
|
* server.addProtoService(protobuf_service_descriptor, service_implementation);
|
|
* server.bind('address:port', server_credential);
|
|
* server.start();
|
|
* ```
|
|
*/
|
|
constructor(options?: object);
|
|
|
|
/**
|
|
* Start the server and begin handling requests
|
|
*/
|
|
start(): void;
|
|
|
|
/**
|
|
* Registers a handler to handle the named method. Fails if there already is
|
|
* a handler for the given method. Returns true on success
|
|
* @param name The name of the method that the provided function should
|
|
* handle/respond to.
|
|
* @param handler Function that takes a stream of
|
|
* request values and returns a stream of response values
|
|
* @param serialize Serialization function for responses
|
|
* @param deserialize Deserialization function for requests
|
|
* @param type The streaming type of method that this handles
|
|
* @return True if the handler was set. False if a handler was already
|
|
* set for that name.
|
|
*/
|
|
register<RequestType, ResponseType>(
|
|
name: string,
|
|
handler: handleCall<RequestType, ResponseType>,
|
|
serialize: serialize<ResponseType>,
|
|
deserialize: deserialize<RequestType>,
|
|
type: string
|
|
): boolean;
|
|
|
|
/**
|
|
* Gracefully shuts down the server. The server will stop receiving new calls,
|
|
* and any pending calls will complete. The callback will be called when all
|
|
* pending calls have completed and the server is fully shut down. This method
|
|
* is idempotent with itself and forceShutdown.
|
|
* @param {function()} callback The shutdown complete callback
|
|
*/
|
|
tryShutdown(callback: () => void): void;
|
|
|
|
/**
|
|
* Forcibly shuts down the server. The server will stop receiving new calls
|
|
* and cancel all pending calls. When it returns, the server has shut down.
|
|
* This method is idempotent with itself and tryShutdown, and it will trigger
|
|
* any outstanding tryShutdown callbacks.
|
|
*/
|
|
forceShutdown(): void;
|
|
|
|
/**
|
|
* Add a service to the server, with a corresponding implementation.
|
|
* @param service The service descriptor
|
|
* @param implementation Map of method names to method implementation
|
|
* for the provided service.
|
|
*/
|
|
addService<ImplementationType = UntypedServiceImplementation>(
|
|
service: ServiceDefinition<ImplementationType>,
|
|
implementation: ImplementationType
|
|
): void;
|
|
|
|
/**
|
|
* Add a proto service to the server, with a corresponding implementation
|
|
* @deprecated Use `Server#addService` instead
|
|
* @param service The proto service descriptor
|
|
* @param implementation Map of method names to method implementation
|
|
* for the provided service.
|
|
*/
|
|
addProtoService<ImplementationType = UntypedServiceImplementation>(
|
|
service: ServiceDefinition<ImplementationType>,
|
|
implementation: ImplementationType
|
|
): void;
|
|
|
|
/**
|
|
* Binds the server to the given port, with SSL disabled if creds is an
|
|
* insecure credentials object
|
|
* @param port The port that the server should bind on, in the format
|
|
* "address:port"
|
|
* @param creds Server credential object to be used for SSL. Pass an
|
|
* insecure credentials object for an insecure port.
|
|
* @return The bound port number or 0 if the opreation failed.
|
|
*/
|
|
bind(port: string, creds: ServerCredentials): number;
|
|
}
|
|
|
|
/**
|
|
* A type that servers as a default for an untyped service.
|
|
*/
|
|
export type UntypedServiceImplementation = { [name: string]: handleCall<any, any> };
|
|
|
|
/**
|
|
* An object that completely defines a service.
|
|
*/
|
|
export type ServiceDefinition<ImplementationType> = {
|
|
readonly [I in keyof ImplementationType]: MethodDefinition<any, any>;
|
|
}
|
|
|
|
/**
|
|
* An object that defines a package containing multiple services
|
|
*/
|
|
export type PackageDefinition = {
|
|
readonly [fullyQualifiedName: string]: ServiceDefinition<any>;
|
|
}
|
|
|
|
/**
|
|
* An object that completely defines a service method signature.
|
|
*/
|
|
export interface MethodDefinition<RequestType, ResponseType> {
|
|
/**
|
|
* The method's URL path
|
|
*/
|
|
path: string;
|
|
/**
|
|
* Indicates whether the method accepts a stream of requests
|
|
*/
|
|
requestStream: boolean;
|
|
/**
|
|
* Indicates whether the method returns a stream of responses
|
|
*/
|
|
responseStream: boolean;
|
|
/**
|
|
* Serialization function for request values
|
|
*/
|
|
requestSerialize: serialize<RequestType>;
|
|
/**
|
|
* Serialization function for response values
|
|
*/
|
|
responseSerialize: serialize<ResponseType>;
|
|
/**
|
|
* Deserialization function for request data
|
|
*/
|
|
requestDeserialize: deserialize<RequestType>;
|
|
/**
|
|
* Deserialization function for repsonse data
|
|
*/
|
|
responseDeserialize: deserialize<ResponseType>;
|
|
}
|
|
|
|
type handleCall<RequestType, ResponseType> =
|
|
handleUnaryCall<RequestType, ResponseType> |
|
|
handleClientStreamingCall<RequestType, ResponseType> |
|
|
handleServerStreamingCall<RequestType, ResponseType> |
|
|
handleBidiStreamingCall<RequestType, ResponseType>;
|
|
|
|
/**
|
|
* User-provided method to handle unary requests on a server
|
|
*/
|
|
type handleUnaryCall<RequestType, ResponseType> =
|
|
(call: ServerUnaryCall<RequestType>, callback: sendUnaryData<ResponseType>) => void;
|
|
|
|
/**
|
|
* An EventEmitter. Used for unary calls.
|
|
*/
|
|
export class ServerUnaryCall<RequestType> {
|
|
/**
|
|
* Indicates if the call has been cancelled
|
|
*/
|
|
cancelled: boolean;
|
|
|
|
/**
|
|
* The request metadata from the client
|
|
*/
|
|
metadata: Metadata;
|
|
|
|
/**
|
|
* The request message from the client
|
|
*/
|
|
request: RequestType;
|
|
|
|
private constructor();
|
|
|
|
/**
|
|
* Get the endpoint this call/stream is connected to.
|
|
* @return The URI of the endpoint
|
|
*/
|
|
getPeer(): string;
|
|
|
|
/**
|
|
* Send the initial metadata for a writable stream.
|
|
* @param responseMetadata Metadata to send
|
|
*/
|
|
sendMetadata(responseMetadata: Metadata): void;
|
|
}
|
|
|
|
/**
|
|
* User provided method to handle client streaming methods on the server.
|
|
*/
|
|
type handleClientStreamingCall<RequestType, ResponseType> =
|
|
(call: ServerReadableStream<RequestType>, callback: sendUnaryData<ResponseType>) => void;
|
|
|
|
/**
|
|
* A stream that the server can read from. Used for calls that are streaming
|
|
* from the client side.
|
|
*/
|
|
export class ServerReadableStream<RequestType> extends Readable {
|
|
/**
|
|
* Indicates if the call has been cancelled
|
|
*/
|
|
cancelled: boolean;
|
|
|
|
/**
|
|
* The request metadata from the client
|
|
*/
|
|
metadata: Metadata;
|
|
|
|
private constructor();
|
|
|
|
/**
|
|
* Get the endpoint this call/stream is connected to.
|
|
* @return The URI of the endpoint
|
|
*/
|
|
getPeer(): string;
|
|
|
|
/**
|
|
* Send the initial metadata for a writable stream.
|
|
* @param responseMetadata Metadata to send
|
|
*/
|
|
sendMetadata(responseMetadata: Metadata): void;
|
|
}
|
|
|
|
/**
|
|
* User provided method to handle server streaming methods on the server.
|
|
*/
|
|
type handleServerStreamingCall<RequestType, ResponseType> =
|
|
(call: ServerWriteableStream<RequestType>) => void;
|
|
|
|
/**
|
|
* A stream that the server can write to. Used for calls that are streaming
|
|
* from the server side.
|
|
*/
|
|
export class ServerWriteableStream<RequestType> extends Writable {
|
|
/**
|
|
* Indicates if the call has been cancelled
|
|
*/
|
|
cancelled: boolean;
|
|
|
|
/**
|
|
* The request metadata from the client
|
|
*/
|
|
metadata: Metadata;
|
|
|
|
/**
|
|
* The request message from the client
|
|
*/
|
|
request: RequestType;
|
|
|
|
private constructor();
|
|
|
|
/**
|
|
* Get the endpoint this call/stream is connected to.
|
|
* @return The URI of the endpoint
|
|
*/
|
|
getPeer(): string;
|
|
|
|
/**
|
|
* Send the initial metadata for a writable stream.
|
|
* @param responseMetadata Metadata to send
|
|
*/
|
|
sendMetadata(responseMetadata: Metadata): void;
|
|
}
|
|
|
|
/**
|
|
* User provided method to handle bidirectional streaming calls on the server.
|
|
*/
|
|
type handleBidiStreamingCall<RequestType, ResponseType> =
|
|
(call: ServerDuplexStream<RequestType, ResponseType>) => void;
|
|
|
|
/**
|
|
* A stream that the server can read from or write to. Used for calls
|
|
* with duplex streaming.
|
|
*/
|
|
export class ServerDuplexStream<RequestType, ResponseType> extends Duplex {
|
|
/**
|
|
* Indicates if the call has been cancelled
|
|
*/
|
|
cancelled: boolean;
|
|
|
|
/**
|
|
* The request metadata from the client
|
|
*/
|
|
metadata: Metadata;
|
|
|
|
private constructor();
|
|
|
|
/**
|
|
* Get the endpoint this call/stream is connected to.
|
|
* @return The URI of the endpoint
|
|
*/
|
|
getPeer(): string;
|
|
|
|
/**
|
|
* Send the initial metadata for a writable stream.
|
|
* @param responseMetadata Metadata to send
|
|
*/
|
|
sendMetadata(responseMetadata: Metadata): void;
|
|
}
|
|
|
|
/**
|
|
* A deserialization function
|
|
* @param data The byte sequence to deserialize
|
|
* @return The data deserialized as a value
|
|
*/
|
|
type deserialize<T> = (data: Buffer) => T;
|
|
|
|
/**
|
|
* A serialization function
|
|
* @param value The value to serialize
|
|
* @return The value serialized as a byte sequence
|
|
*/
|
|
type serialize<T> = (value: T) => Buffer;
|
|
|
|
/**
|
|
* Callback function passed to server handlers that handle methods with
|
|
* unary responses.
|
|
*/
|
|
type sendUnaryData<ResponseType> =
|
|
(error: ServiceError | null, value: ResponseType | null, trailer?: Metadata, flags?: number) => void;
|
|
|
|
/**
|
|
* A class for storing metadata. Keys are normalized to lowercase ASCII.
|
|
*/
|
|
export class Metadata {
|
|
/**
|
|
* Sets the given value for the given key by replacing any other values
|
|
* associated with that key. Normalizes the key.
|
|
* @param key The key to whose value should be set.
|
|
* @param value The value to set. Must be a buffer if and only
|
|
* if the normalized key ends with '-bin'.
|
|
*/
|
|
set(key: string, value: MetadataValue): void;
|
|
|
|
/**
|
|
* Adds the given value for the given key by appending to a list of previous
|
|
* values associated with that key. Normalizes the key.
|
|
* @param key The key for which a new value should be appended.
|
|
* @param value The value to add. Must be a buffer if and only
|
|
* if the normalized key ends with '-bin'.
|
|
*/
|
|
add(key: string, value: MetadataValue): void;
|
|
|
|
/**
|
|
* Removes the given key and any associated values. Normalizes the key.
|
|
* @param key The key whose values should be removed.
|
|
*/
|
|
remove(key: string): void;
|
|
|
|
/**
|
|
* Gets a list of all values associated with the key. Normalizes the key.
|
|
* @param key The key whose value should be retrieved.
|
|
* @return A list of values associated with the given key.
|
|
*/
|
|
get(key: string): MetadataValue[];
|
|
|
|
/**
|
|
* Gets a plain object mapping each key to the first value associated with it.
|
|
* This reflects the most common way that people will want to see metadata.
|
|
* @return A key/value mapping of the metadata.
|
|
*/
|
|
getMap(): { [key: string]: MetadataValue };
|
|
|
|
/**
|
|
* Clones the metadata object.
|
|
* @return The newly cloned object.
|
|
*/
|
|
clone(): Metadata;
|
|
}
|
|
|
|
export type MetadataValue = string | Buffer;
|
|
|
|
/**
|
|
* Represents the status of a completed request. If `code` is
|
|
* `grpc.status.OK`, then the request has completed successfully.
|
|
* Otherwise, the request has failed, `details` will contain a description of
|
|
* the error. Either way, `metadata` contains the trailing response metadata
|
|
* sent by the server when it finishes processing the call.
|
|
*/
|
|
export interface StatusObject {
|
|
/**
|
|
* The error code, a key of `grpc.status`
|
|
*/
|
|
code: status;
|
|
/**
|
|
* Human-readable description of the status
|
|
*/
|
|
details: string;
|
|
/**
|
|
* Trailing metadata sent with the status, if applicable
|
|
*/
|
|
metadata: Metadata;
|
|
}
|
|
|
|
/**
|
|
* Describes how a request has failed. The member `message` will be the same as
|
|
* `details` in `StatusObject`, and `code` and `metadata` are the
|
|
* same as in that object.
|
|
*/
|
|
export interface ServiceError extends Error {
|
|
/**
|
|
* The error code, a key of {@link grpc.status} that is not `grpc.status.OK`
|
|
*/
|
|
code?: status;
|
|
/**
|
|
* Trailing metadata sent with the status, if applicable
|
|
*/
|
|
metadata?: Metadata;
|
|
}
|
|
|
|
/**
|
|
* ServerCredentials factories
|
|
*/
|
|
export class ServerCredentials {
|
|
/**
|
|
* Create insecure server credentials
|
|
* @return The ServerCredentials
|
|
*/
|
|
static createInsecure(): ServerCredentials;
|
|
/**
|
|
* Create SSL server credentials
|
|
* @param rootCerts Root CA certificates for validating client certificates
|
|
* @param keyCertPairs A list of private key and certificate chain pairs to
|
|
* be used for authenticating the server
|
|
* @param checkClientCertificate Indicates that the server should request
|
|
* and verify the client's certificates.
|
|
* Defaults to `false`.
|
|
* @return The ServerCredentials
|
|
*/
|
|
static createSsl(rootCerts: Buffer | null, keyCertPairs: KeyCertPair[], checkClientCertificate?: boolean): ServerCredentials;
|
|
}
|
|
|
|
/**
|
|
* A private key and certificate pair
|
|
*/
|
|
export interface KeyCertPair {
|
|
/**
|
|
* The server's private key
|
|
*/
|
|
private_key: Buffer;
|
|
|
|
/**
|
|
* The server's certificate chain
|
|
*/
|
|
cert_chain: Buffer;
|
|
}
|
|
|
|
/**
|
|
* Enum of status codes that gRPC can return
|
|
*/
|
|
export enum status {
|
|
/**
|
|
* Not an error; returned on success
|
|
*/
|
|
OK = 0,
|
|
/**
|
|
* The operation was cancelled (typically by the caller).
|
|
*/
|
|
CANCELLED = 1,
|
|
/**
|
|
* Unknown error. An example of where this error may be returned is
|
|
* if a status value received from another address space belongs to
|
|
* an error-space that is not known in this address space. Also
|
|
* errors raised by APIs that do not return enough error information
|
|
* may be converted to this error.
|
|
*/
|
|
UNKNOWN = 2,
|
|
/**
|
|
* Client specified an invalid argument. Note that this differs
|
|
* from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments
|
|
* that are problematic regardless of the state of the system
|
|
* (e.g., a malformed file name).
|
|
*/
|
|
INVALID_ARGUMENT = 3,
|
|
/**
|
|
* Deadline expired before operation could complete. For operations
|
|
* that change the state of the system, this error may be returned
|
|
* even if the operation has completed successfully. For example, a
|
|
* successful response from a server could have been delayed long
|
|
* enough for the deadline to expire.
|
|
*/
|
|
DEADLINE_EXCEEDED = 4,
|
|
/**
|
|
* Some requested entity (e.g., file or directory) was not found.
|
|
*/
|
|
NOT_FOUND = 5,
|
|
/**
|
|
* Some entity that we attempted to create (e.g., file or directory)
|
|
* already exists.
|
|
*/
|
|
ALREADY_EXISTS = 6,
|
|
/**
|
|
* The caller does not have permission to execute the specified
|
|
* operation. PERMISSION_DENIED must not be used for rejections
|
|
* caused by exhausting some resource (use RESOURCE_EXHAUSTED
|
|
* instead for those errors). PERMISSION_DENIED must not be
|
|
* used if the caller can not be identified (use UNAUTHENTICATED
|
|
* instead for those errors).
|
|
*/
|
|
PERMISSION_DENIED = 7,
|
|
/**
|
|
* Some resource has been exhausted, perhaps a per-user quota, or
|
|
* perhaps the entire file system is out of space.
|
|
*/
|
|
RESOURCE_EXHAUSTED = 8,
|
|
/**
|
|
* Operation was rejected because the system is not in a state
|
|
* required for the operation's execution. For example, directory
|
|
* to be deleted may be non-empty, an rmdir operation is applied to
|
|
* a non-directory, etc.
|
|
*
|
|
* A litmus test that may help a service implementor in deciding
|
|
* between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE:
|
|
*
|
|
* - Use UNAVAILABLE if the client can retry just the failing call.
|
|
* - Use ABORTED if the client should retry at a higher-level
|
|
* (e.g., restarting a read-modify-write sequence).
|
|
* - Use FAILED_PRECONDITION if the client should not retry until
|
|
* the system state has been explicitly fixed. E.g., if an "rmdir"
|
|
* fails because the directory is non-empty, FAILED_PRECONDITION
|
|
* should be returned since the client should not retry unless
|
|
* they have first fixed up the directory by deleting files from it.
|
|
* - Use FAILED_PRECONDITION if the client performs conditional
|
|
* REST Get/Update/Delete on a resource and the resource on the
|
|
* server does not match the condition. E.g., conflicting
|
|
* read-modify-write on the same resource.
|
|
*/
|
|
FAILED_PRECONDITION = 9,
|
|
/**
|
|
* The operation was aborted, typically due to a concurrency issue
|
|
* like sequencer check failures, transaction aborts, etc.
|
|
*
|
|
* See litmus test above for deciding between FAILED_PRECONDITION,
|
|
* ABORTED, and UNAVAILABLE.
|
|
*/
|
|
ABORTED = 10,
|
|
/**
|
|
* Operation was attempted past the valid range. E.g., seeking or
|
|
* reading past end of file.
|
|
*
|
|
* Unlike INVALID_ARGUMENT, this error indicates a problem that may
|
|
* be fixed if the system state changes. For example, a 32-bit file
|
|
* system will generate INVALID_ARGUMENT if asked to read at an
|
|
* offset that is not in the range [0,2^32-1], but it will generate
|
|
* OUT_OF_RANGE if asked to read from an offset past the current
|
|
* file size.
|
|
*
|
|
* There is a fair bit of overlap between FAILED_PRECONDITION and
|
|
* OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific
|
|
* error) when it applies so that callers who are iterating through
|
|
* a space can easily look for an OUT_OF_RANGE error to detect when
|
|
* they are done.
|
|
*/
|
|
OUT_OF_RANGE = 11,
|
|
/**
|
|
* Operation is not implemented or not supported/enabled in this service.
|
|
*/
|
|
UNIMPLEMENTED = 12,
|
|
/**
|
|
* Internal errors. Means some invariants expected by underlying
|
|
* system has been broken. If you see one of these errors,
|
|
* something is very broken.
|
|
*/
|
|
INTERNAL = 13,
|
|
/**
|
|
* The service is currently unavailable. This is a most likely a
|
|
* transient condition and may be corrected by retrying with
|
|
* a backoff.
|
|
*
|
|
* See litmus test above for deciding between FAILED_PRECONDITION,
|
|
* ABORTED, and UNAVAILABLE.
|
|
*/
|
|
UNAVAILABLE = 14,
|
|
/**
|
|
* Unrecoverable data loss or corruption.
|
|
*/
|
|
DATA_LOSS = 15,
|
|
/**
|
|
* The request does not have valid authentication credentials for the
|
|
* operation.
|
|
*/
|
|
UNAUTHENTICATED = 16,
|
|
}
|
|
|
|
/**
|
|
* Propagation flags: these can be bitwise or-ed to form the propagation option
|
|
* for calls.
|
|
*
|
|
* Users are encouraged to write propagation masks as deltas from the default.
|
|
* i.e. write `grpc.propagate.DEFAULTS & ~grpc.propagate.DEADLINE` to disable
|
|
* deadline propagation.
|
|
*/
|
|
export enum propagate {
|
|
DEADLINE,
|
|
CENSUS_STATS_CONTEXT,
|
|
CENSUS_TRACING_CONTEXT,
|
|
CANCELLATION,
|
|
DEFAULTS,
|
|
}
|
|
|
|
/**
|
|
* Call error constants. Call errors almost always indicate bugs in the gRPC
|
|
* library, and these error codes are mainly useful for finding those bugs.
|
|
*/
|
|
export enum callError {
|
|
OK,
|
|
ERROR,
|
|
NOT_ON_SERVER,
|
|
NOT_ON_CLIENT,
|
|
ALREADY_INVOKED,
|
|
NOT_INVOKED,
|
|
ALREADY_FINISHED,
|
|
TOO_MANY_OPERATIONS,
|
|
INVALID_FLAGS,
|
|
INVALID_METADATA,
|
|
INVALID_MESSAGE,
|
|
NOT_SERVER_COMPLETION_QUEUE,
|
|
BATCH_TOO_BIG,
|
|
PAYLOAD_TYPE_MISMATCH,
|
|
}
|
|
|
|
/**
|
|
* Write flags: these can be bitwise or-ed to form write options that modify
|
|
* how data is written.
|
|
*/
|
|
export enum writeFlags {
|
|
/**
|
|
* Hint that the write may be buffered and need not go out on the wire
|
|
* immediately. GRPC is free to buffer the message until the next non-buffered
|
|
* write, or until writes_done, but it need not buffer completely or at all.
|
|
*/
|
|
BUFFER_HINT = 1,
|
|
/**
|
|
* Force compression to be disabled for a particular write
|
|
*/
|
|
NO_COMPRESS,
|
|
}
|
|
|
|
/**
|
|
* Log verbosity constants. Maps setting names to code numbers.
|
|
*/
|
|
export enum logVerbosity {
|
|
DEBUG,
|
|
INFO,
|
|
ERROR,
|
|
}
|
|
|
|
/**
|
|
* Credentials module
|
|
*
|
|
* This module contains factory methods for two different credential types:
|
|
* CallCredentials and ChannelCredentials. ChannelCredentials are things like
|
|
* SSL credentials that can be used to secure a connection, and are used to
|
|
* construct a Client object. CallCredentials generally modify metadata, so they
|
|
* can be attached to an individual method call.
|
|
*
|
|
* CallCredentials can be composed with other CallCredentials to create
|
|
* CallCredentials. ChannelCredentials can be composed with CallCredentials
|
|
* to create ChannelCredentials. No combined credential can have more than
|
|
* one ChannelCredentials.
|
|
*
|
|
* For example, to create a client secured with SSL that uses Google
|
|
* default application credentials to authenticate:
|
|
*
|
|
* ```
|
|
* var channel_creds = credentials.createSsl(root_certs);
|
|
* (new GoogleAuth()).getApplicationDefault(function(err, credential) {
|
|
* var call_creds = credentials.createFromGoogleCredential(credential);
|
|
* var combined_creds = credentials.combineChannelCredentials(
|
|
* channel_creds, call_creds);
|
|
* var client = new Client(address, combined_creds);
|
|
* });
|
|
* ```
|
|
*/
|
|
export const credentials: {
|
|
/**
|
|
* Create an SSL Credentials object. If using a client-side certificate, both
|
|
* the second and third arguments must be passed.
|
|
* @param rootCerts The root certificate data
|
|
* @param privateKey The client certificate private key, if applicable
|
|
* @param certChain The client certificate cert chain, if applicable
|
|
* @return The SSL Credentials object
|
|
*/
|
|
createSsl(rootCerts?: Buffer, privateKey?: Buffer, certChain?: Buffer): ChannelCredentials;
|
|
|
|
/**
|
|
* Create a gRPC credentials object from a metadata generation function. This
|
|
* function gets the service URL and a callback as parameters. The error
|
|
* passed to the callback can optionally have a 'code' value attached to it,
|
|
* which corresponds to a status code that this library uses.
|
|
* @param metadataGenerator The function that generates metadata
|
|
* @return The credentials object
|
|
*/
|
|
createFromMetadataGenerator(metadataGenerator: metadataGenerator): CallCredentials;
|
|
|
|
/**
|
|
* Create a gRPC credential from a Google credential object.
|
|
* @param googleCredential The Google credential object to use
|
|
* @return The resulting credentials object
|
|
*/
|
|
createFromGoogleCredential(googleCredential: GoogleOAuth2Client): CallCredentials;
|
|
|
|
/**
|
|
* Combine a ChannelCredentials with any number of CallCredentials into a single
|
|
* ChannelCredentials object.
|
|
* @param channelCredential The ChannelCredentials to start with
|
|
* @param credentials The CallCredentials to compose
|
|
* @return A credentials object that combines all of the input credentials
|
|
*/
|
|
combineChannelCredentials(channelCredential: ChannelCredentials, ...credentials: CallCredentials[]): ChannelCredentials;
|
|
|
|
/**
|
|
* Combine any number of CallCredentials into a single CallCredentials object
|
|
* @param credentials The CallCredentials to compose
|
|
* @return A credentials object that combines all of the input credentials
|
|
*/
|
|
combineCallCredentials(...credentials: CallCredentials[]): CallCredentials;
|
|
|
|
/**
|
|
* Create an insecure credentials object. This is used to create a channel that
|
|
* does not use SSL. This cannot be composed with anything.
|
|
* @return The insecure credentials object
|
|
*/
|
|
createInsecure(): ChannelCredentials;
|
|
};
|
|
|
|
/**
|
|
* Metadata generator function.
|
|
*/
|
|
export type metadataGenerator = (params: { service_url: string }, callback: (error: Error | null, metadata?: Metadata) => void) => void;
|
|
|
|
/**
|
|
* This cannot be constructed directly. Instead, instances of this class should
|
|
* be created using the factory functions in `grpc.credentials`
|
|
*/
|
|
export interface ChannelCredentials {
|
|
/**
|
|
* Returns a copy of this object with the included set of per-call credentials
|
|
* expanded to include callCredentials.
|
|
* @param callCredentials A CallCredentials object to associate with this
|
|
* instance.
|
|
*/
|
|
compose(callCredentials: CallCredentials): ChannelCredentials;
|
|
|
|
/**
|
|
* Gets the set of per-call credentials associated with this instance.
|
|
*/
|
|
getCallCredentials(): CallCredentials;
|
|
|
|
/**
|
|
* Gets a SecureContext object generated from input parameters if this
|
|
* instance was created with createSsl, or null if this instance was created
|
|
* with createInsecure.
|
|
*/
|
|
getSecureContext(): SecureContext | null;
|
|
}
|
|
|
|
/**
|
|
* This cannot be constructed directly. Instead, instances of this class should
|
|
* be created using the factory functions in `grpc.credentials`
|
|
*/
|
|
export interface CallCredentials {
|
|
/**
|
|
* Asynchronously generates a new Metadata object.
|
|
* @param options Options used in generating the Metadata object.
|
|
*/
|
|
generateMetadata(options: object): Promise<Metadata>;
|
|
|
|
/**
|
|
* Creates a new CallCredentials object from properties of both this and
|
|
* another CallCredentials object. This object's metadata generator will be
|
|
* called first.
|
|
* @param callCredentials The other CallCredentials object.
|
|
*/
|
|
compose(callCredentials: CallCredentials): CallCredentials;
|
|
}
|
|
|
|
/**
|
|
* This is the required interface from the OAuth2Client object
|
|
* from https://github.com/google/google-auth-library-nodejs lib.
|
|
* The definition is copied from `ts/lib/auth/oauth2client.ts`
|
|
*/
|
|
export interface GoogleOAuth2Client {
|
|
getRequestMetadata(optUri: string, metadataCallback: (err: Error, headers: any) => void): void;
|
|
}
|
|
|
|
/**
|
|
* Creates a constructor for a client with the given methods, as specified in
|
|
* the methods argument. The resulting class will have an instance method for
|
|
* each method in the service, which is a partial application of one of the
|
|
* `grpc.Client` request methods, depending on `requestSerialize`
|
|
* and `responseSerialize`, with the `method`, `serialize`, and `deserialize`
|
|
* arguments predefined.
|
|
* @param methods An object mapping method names to method attributes
|
|
* @param serviceName The fully qualified name of the service
|
|
* @param classOptions An options object.
|
|
* @return New client constructor, which is a subclass of `grpc.Client`, and
|
|
* has the same arguments as that constructor.
|
|
*/
|
|
export function makeGenericClientConstructor(
|
|
methods: ServiceDefinition<any>,
|
|
serviceName: string,
|
|
classOptions: GenericClientOptions,
|
|
): typeof Client;
|
|
|
|
/**
|
|
* Options for generic client constructor.
|
|
*/
|
|
export interface GenericClientOptions {
|
|
/**
|
|
* Indicates that the old argument order should be used for methods, with
|
|
* optional arguments at the end instead of the callback at the end. This
|
|
* option is only a temporary stopgap measure to smooth an API breakage.
|
|
* It is deprecated, and new code should not use it.
|
|
*/
|
|
deprecatedArgumentOrder?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Create a client with the given methods
|
|
*/
|
|
export class Client {
|
|
/**
|
|
* A generic gRPC client. Primarily useful as a base class for generated clients
|
|
* @param address Server address to connect to
|
|
* @param credentials Credentials to use to connect to the server
|
|
* @param options Options to apply to channel creation
|
|
*/
|
|
constructor(address: string, credentials: ChannelCredentials, options?: object)
|
|
|
|
/**
|
|
* Make a unary request to the given method, using the given serialize
|
|
* and deserialize functions, with the given argument.
|
|
* @param method The name of the method to request
|
|
* @param serialize The serialization function for inputs
|
|
* @param deserialize The deserialization function for outputs
|
|
* @param argument The argument to the call. Should be serializable with
|
|
* serialize
|
|
* @param metadata Metadata to add to the call
|
|
* @param options Options map
|
|
* @param callback The callback to for when the response is received
|
|
* @return An event emitter for stream related events
|
|
*/
|
|
makeUnaryRequest<RequestType, ResponseType>(
|
|
method: string,
|
|
serialize: serialize<RequestType>,
|
|
deserialize: deserialize<ResponseType>,
|
|
argument: RequestType | null,
|
|
metadata: Metadata | null,
|
|
options: CallOptions | null,
|
|
callback: requestCallback<ResponseType>,
|
|
): ClientUnaryCall;
|
|
|
|
/**
|
|
* Make a client stream request to the given method, using the given serialize
|
|
* and deserialize functions, with the given argument.
|
|
* @param method The name of the method to request
|
|
* @param serialize The serialization function for inputs
|
|
* @param deserialize The deserialization function for outputs
|
|
* @param metadata Array of metadata key/value pairs to add to the call
|
|
* @param options Options map
|
|
* @param callback The callback to for when the response is received
|
|
* @return An event emitter for stream related events
|
|
*/
|
|
makeClientStreamRequest<RequestType, ResponseType>(
|
|
method: string,
|
|
serialize: serialize<RequestType>,
|
|
deserialize: deserialize<ResponseType>,
|
|
metadata: Metadata | null,
|
|
options: CallOptions | null,
|
|
callback: requestCallback<ResponseType>,
|
|
): ClientWritableStream<RequestType>;
|
|
|
|
/**
|
|
* Make a server stream request to the given method, with the given serialize
|
|
* and deserialize function, using the given argument
|
|
* @param method The name of the method to request
|
|
* @param serialize The serialization function for inputs
|
|
* @param deserialize The deserialization function for outputs
|
|
* @param argument The argument to the call. Should be serializable with
|
|
* serialize
|
|
* @param metadata Array of metadata key/value pairs to add to the call
|
|
* @param options Options map
|
|
* @return An event emitter for stream related events
|
|
*/
|
|
makeServerStreamRequest<RequestType, ResponseType>(
|
|
method: string,
|
|
serialize: serialize<RequestType>,
|
|
deserialize: deserialize<ResponseType>,
|
|
argument: RequestType,
|
|
metadata?: Metadata | null,
|
|
options?: CallOptions | null,
|
|
): ClientReadableStream<RequestType>;
|
|
|
|
/**
|
|
* Make a bidirectional stream request with this method on the given channel.
|
|
* @param method The name of the method to request
|
|
* @param serialize The serialization function for inputs
|
|
* @param deserialize The deserialization
|
|
* function for outputs
|
|
* @param metadata Array of metadata key/value
|
|
* pairs to add to the call
|
|
* @param options Options map
|
|
* @return An event emitter for stream related events
|
|
*/
|
|
makeBidiStreamRequest<RequestType, ResponseType>(
|
|
method: string,
|
|
serialize: serialize<RequestType>,
|
|
deserialize: deserialize<ResponseType>,
|
|
metadata?: Metadata | null,
|
|
options?: CallOptions | null,
|
|
): ClientDuplexStream<RequestType, ResponseType>;
|
|
|
|
/**
|
|
* Close this client.
|
|
*/
|
|
close(): void;
|
|
|
|
/**
|
|
* Return the underlying channel object for the specified client
|
|
* @return The channel
|
|
*/
|
|
getChannel(): Channel;
|
|
|
|
/**
|
|
* Wait for the client to be ready. The callback will be called when the
|
|
* client has successfully connected to the server, and it will be called
|
|
* with an error if the attempt to connect to the server has unrecoverablly
|
|
* failed or if the deadline expires. This function will make the channel
|
|
* start connecting if it has not already done so.
|
|
* @param deadline When to stop waiting for a connection.
|
|
* @param callback The callback to call when done attempting to connect.
|
|
*/
|
|
waitForReady(deadline: Deadline, callback: (error: Error | null) => void): void;
|
|
}
|
|
|
|
/**
|
|
* A gRPC channel.
|
|
*/
|
|
export type Channel = any;
|
|
|
|
/**
|
|
* Options that can be set on a call.
|
|
*/
|
|
export interface CallOptions {
|
|
/**
|
|
* The deadline for the entire call to complete.
|
|
*/
|
|
deadline?: Deadline;
|
|
/**
|
|
* Server hostname to set on the call. Only meaningful if different from
|
|
* the server address used to construct the client.
|
|
*/
|
|
host?: string;
|
|
/**
|
|
* Parent call. Used in servers when making a call as part of the process
|
|
* of handling a call. Used to propagate some information automatically,
|
|
* as specified by propagate_flags.
|
|
*/
|
|
parent?: Call;
|
|
/**
|
|
* Indicates which properties of a parent call should propagate to this
|
|
* call. Bitwise combination of flags in `grpc.propagate`.
|
|
*/
|
|
propagate_flags: number;
|
|
/**
|
|
* The credentials that should be used to make this particular call.
|
|
*/
|
|
credentials: CallCredentials;
|
|
}
|
|
|
|
/**
|
|
* The deadline of an operation. If it is a date, the deadline is reached at
|
|
* the date and time specified. If it is a finite number, it is treated as
|
|
* a number of milliseconds since the Unix Epoch. If it is Infinity, the
|
|
* deadline will never be reached. If it is -Infinity, the deadline has already
|
|
* passed.
|
|
*/
|
|
export type Deadline = number | Date;
|
|
|
|
/**
|
|
* Any client call type
|
|
*/
|
|
type Call =
|
|
ClientUnaryCall |
|
|
ClientReadableStream<any> |
|
|
ClientWritableStream<any> |
|
|
ClientDuplexStream<any, any>;
|
|
|
|
/**
|
|
* An EventEmitter. Used for unary calls.
|
|
*/
|
|
export class ClientUnaryCall {
|
|
private constructor();
|
|
|
|
/**
|
|
* Cancel the ongoing call. Results in the call ending with a CANCELLED status,
|
|
* unless it has already ended with some other status.
|
|
*/
|
|
cancel(): void;
|
|
|
|
/**
|
|
* Get the endpoint this call/stream is connected to.
|
|
* @return The URI of the endpoint
|
|
*/
|
|
getPeer(): string;
|
|
}
|
|
|
|
/**
|
|
* A stream that the client can read from. Used for calls that are streaming
|
|
* from the server side.
|
|
*/
|
|
export class ClientReadableStream<ResponseType> extends Readable {
|
|
private constructor();
|
|
|
|
/**
|
|
* Cancel the ongoing call. Results in the call ending with a CANCELLED status,
|
|
* unless it has already ended with some other status.
|
|
*/
|
|
cancel(): void;
|
|
|
|
/**
|
|
* Get the endpoint this call/stream is connected to.
|
|
* @return The URI of the endpoint
|
|
*/
|
|
getPeer(): string;
|
|
}
|
|
|
|
/**
|
|
* A stream that the client can write to. Used for calls that are streaming from
|
|
* the client side.
|
|
*/
|
|
export class ClientWritableStream<RequestType> extends Writable {
|
|
private constructor();
|
|
|
|
/**
|
|
* Write a message to the request stream. If serializing the argument fails,
|
|
* the call will be cancelled and the stream will end with an error.
|
|
* @param message The message to write. Must be a valid argument to the
|
|
* serialize function of the corresponding method
|
|
* @param flags Flags to modify how the message is written
|
|
* @param callback Callback for when this chunk of data is flushed
|
|
* @return As defined for [Writable]{@link external:Writable}
|
|
*/
|
|
write(message: RequestType, flags?: any&writeFlags, callback?: Function): boolean;
|
|
|
|
/**
|
|
* Cancel the ongoing call. Results in the call ending with a CANCELLED status,
|
|
* unless it has already ended with some other status.
|
|
*/
|
|
cancel(): void;
|
|
|
|
/**
|
|
* Get the endpoint this call/stream is connected to.
|
|
* @return The URI of the endpoint
|
|
*/
|
|
getPeer(): string;
|
|
}
|
|
|
|
/**
|
|
* A stream that the client can read from or write to. Used for calls with
|
|
* duplex streaming.
|
|
*/
|
|
export class ClientDuplexStream<RequestType, ResponseType> extends Duplex {
|
|
private constructor();
|
|
|
|
/**
|
|
* Write a message to the request stream. If serializing the argument fails,
|
|
* the call will be cancelled and the stream will end with an error.
|
|
* @param message The message to write. Must be a valid argument to the
|
|
* serialize function of the corresponding method
|
|
* @param flags Flags to modify how the message is written
|
|
* @param callback Callback for when this chunk of data is flushed
|
|
* @return As defined for [Writable]{@link external:Writable}
|
|
*/
|
|
write(message: RequestType, flags?: any&writeFlags, callback?: Function): boolean;
|
|
|
|
/**
|
|
* Cancel the ongoing call. Results in the call ending with a CANCELLED status,
|
|
* unless it has already ended with some other status.
|
|
*/
|
|
cancel(): void;
|
|
|
|
/**
|
|
* Get the endpoint this call/stream is connected to.
|
|
* @return The URI of the endpoint
|
|
*/
|
|
getPeer(): string;
|
|
}
|
|
|
|
/**
|
|
* Client request callback
|
|
* @param error The error, if the call failed
|
|
* @param value The response value, if the call succeeded
|
|
*/
|
|
export type requestCallback<ResponseType> =
|
|
(error: ServiceError | null, value: ResponseType | undefined) => void;
|
|
|
|
/**
|
|
* Return the underlying channel object for the specified client
|
|
* @see grpc.Client#getChannel
|
|
* @param client The client
|
|
* @return The channel
|
|
*/
|
|
export function getClientChannel(client: Client): Channel;
|
|
|
|
/**
|
|
* Wait for the client to be ready. The callback will be called when the
|
|
* client has successfully connected to the server, and it will be called
|
|
* with an error if the attempt to connect to the server has unrecoverably
|
|
* failed or if the deadline expires. This function will make the channel
|
|
* start connecting if it has not already done so.
|
|
* @see grpc.Client#waitForReady
|
|
* @param client The client to wait on
|
|
* @param deadline When to stop waiting for a connection. Pass Infinity to
|
|
* wait forever.
|
|
* @param callback The callback to call when done attempting to connect.
|
|
*/
|
|
export function waitForClientReady(client: Client, deadline: Deadline, callback: (error: Error | null) => void): void;
|
|
|
|
/**
|
|
* Close client.
|
|
* @param clientObj The client to close
|
|
*/
|
|
export function closeClient(clientObj: Client): void;
|
|
|
|
/**
|
|
* A builder for gRPC status objects
|
|
*/
|
|
export class StatusBuilder {
|
|
constructor()
|
|
|
|
/**
|
|
* Adds a status code to the builder
|
|
* @param code The status code
|
|
*/
|
|
withCode(code: number): this;
|
|
|
|
/**
|
|
* Adds details to the builder
|
|
* @param details A status message
|
|
*/
|
|
withDetails(details: string): this;
|
|
|
|
/**
|
|
* Adds metadata to the builder
|
|
* @param metadata The gRPC status metadata
|
|
*/
|
|
withMetadata(metadata: Metadata): this;
|
|
|
|
/**
|
|
* Builds the status object
|
|
* @return A gRPC status
|
|
*/
|
|
build(): StatusObject;
|
|
}
|
|
|
|
export type MetadataListener = (metadata: Metadata, next: function) => void;
|
|
|
|
export type MessageListener = (message: any, next: function) => void;
|
|
|
|
export type StatusListener = (status: StatusObject, next: function) => void;
|
|
|
|
export interface Listener {
|
|
onReceiveMetadata?: MetadataListener;
|
|
onReceiveMessage?: MessageListener;
|
|
onReceiveStatus?: StatusListener;
|
|
}
|
|
|
|
/**
|
|
* A builder for listener interceptors
|
|
*/
|
|
export class ListenerBuilder {
|
|
constructor();
|
|
|
|
/**
|
|
* Adds onReceiveMetadata method to the builder
|
|
* @param onReceiveMetadata A listener method for receiving metadata
|
|
*/
|
|
withOnReceiveMetadata(onReceiveMetadata: MetadataListener): this;
|
|
|
|
/**
|
|
* Adds onReceiveMessage method to the builder
|
|
* @param onReceiveMessage A listener method for receiving message
|
|
*/
|
|
withOnReceiveMessage(onReceiveMessage: MessageListener): this;
|
|
|
|
/**
|
|
* Adds onReceiveStatus method to the builder
|
|
* @param onReceiveStatus A listener method for receiving status
|
|
*/
|
|
withOnReceiveStatus(onReceiveStatus: StatusListener): this;
|
|
|
|
/**
|
|
* Builds the call listener
|
|
*/
|
|
build(): Listener;
|
|
}
|
|
|
|
export type MetadataRequester = (metadata: Metadata, listener: Listener, next: function) => void;
|
|
|
|
export type MessageRequester = (message: any, next: function) => void;
|
|
|
|
export type CloseRequester = (next: function) => void;
|
|
|
|
export type CancelRequester = (next: function) => void;
|
|
|
|
export type GetPeerRequester = (next: function) => string;
|
|
|
|
export interface Requester {
|
|
start?: MetadataRequester;
|
|
sendMessage?: MessageRequester;
|
|
halfClose?: CloseRequester;
|
|
cancel?: CancelRequester;
|
|
getPeer?: GetPeerRequester;
|
|
}
|
|
|
|
/**
|
|
* A builder for the outbound methods of an interceptor
|
|
*/
|
|
export class RequesterBuilder {
|
|
constructor();
|
|
|
|
/**
|
|
* Add a metadata requester to the builder
|
|
* @param start A requester method for handling metadata
|
|
*/
|
|
withStart(start: MetadataRequester): this;
|
|
|
|
/**
|
|
* Add a message requester to the builder.
|
|
* @param sendMessage A requester method for handling
|
|
* messages.
|
|
*/
|
|
withSendMessage(sendMessage: MessageRequester): this;
|
|
|
|
/**
|
|
* Add a close requester to the builder.
|
|
* @param halfClose A requester method for handling client
|
|
* close.
|
|
*/
|
|
withHalfClose(halfClose: CloseRequester): this;
|
|
|
|
/**
|
|
* Add a cancel requester to the builder.
|
|
* @param cancel A requester method for handling `cancel`
|
|
*/
|
|
withCancel(cancel: CancelRequester): this;
|
|
|
|
/**
|
|
* Builds the requester's interceptor methods.
|
|
*/
|
|
build(): Requester;
|
|
}
|
|
|
|
/**
|
|
* A chainable gRPC call proxy which will delegate to an optional requester
|
|
* object. By default, interceptor methods will chain to nextCall. If a
|
|
* requester is provided which implements an interceptor method, that
|
|
* requester method will be executed as part of the chain.
|
|
* operations.
|
|
*/
|
|
export class InterceptingCall {
|
|
/**
|
|
* @param next_Call The next call in the chain
|
|
* @param requester Interceptor methods to handle request
|
|
*/
|
|
constructor(nextCall: InterceptingCall|null, requester?: Requester);
|
|
|
|
/**
|
|
* Starts a call through the outbound interceptor chain and adds an element to
|
|
* the reciprocal inbound listener chain.
|
|
*/
|
|
start(metadata: Metadata, listener: Listener): void;
|
|
|
|
/**
|
|
* Pass a message through the interceptor chain.
|
|
*/
|
|
sendMessage(message: any): void;
|
|
|
|
/**
|
|
* Run a close operation through the interceptor chain
|
|
*/
|
|
halfClose(): void;
|
|
|
|
/**
|
|
* Run a cancel operation through the interceptor chain
|
|
*/
|
|
cancel(): void;
|
|
|
|
/**
|
|
* Run a cancelWithStatus operation through the interceptor chain.
|
|
* @param status
|
|
* @param message
|
|
*/
|
|
cancelWithStatus(status: StatusObject, message: string): void;
|
|
|
|
/**
|
|
* Pass a getPeer call down to the base gRPC call (should not be intercepted)
|
|
*/
|
|
getPeer(): object;
|
|
|
|
/**
|
|
* For streaming calls, we need to transparently pass the stream's context
|
|
* through the interceptor chain. Passes the context between InterceptingCalls
|
|
* but hides it from any requester implementations.
|
|
* @param context Carries objects needed for streaming operations.
|
|
* @param message The message to send.
|
|
*/
|
|
sendMessageWithContext(context: object, message: any): void;
|
|
|
|
/**
|
|
* For receiving streaming messages, we need to seed the base interceptor with
|
|
* the streaming context to create a RECV_MESSAGE batch.
|
|
* @param context Carries objects needed for streaming operations
|
|
*/
|
|
recvMessageWithContext(context: object): void;
|
|
}
|
|
}
|