From 52d552ce54c30ab5f85b5c6025f2486fa8d1fc7f Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Tue, 19 Sep 2017 11:15:36 -0700 Subject: [PATCH 01/20] Remove some unnecessary files from the native npm package --- packages/grpc-native-core/.npmignore | 1 + packages/grpc-native-core/package.json | 9 ++++++--- .../grpc-native-core/templates/package.json.template | 9 ++++++--- 3 files changed, 13 insertions(+), 6 deletions(-) create mode 100644 packages/grpc-native-core/.npmignore diff --git a/packages/grpc-native-core/.npmignore b/packages/grpc-native-core/.npmignore new file mode 100644 index 00000000..e66c5e92 --- /dev/null +++ b/packages/grpc-native-core/.npmignore @@ -0,0 +1 @@ +**/BUILD \ No newline at end of file diff --git a/packages/grpc-native-core/package.json b/packages/grpc-native-core/package.json index 26d43447..dd8e75f6 100644 --- a/packages/grpc-native-core/package.json +++ b/packages/grpc-native-core/package.json @@ -62,7 +62,6 @@ "files": [ "LICENSE", "README.md", - "deps/grpc/src/proto", "deps/grpc/etc", "index.js", "src", @@ -71,9 +70,13 @@ "deps/grpc/src/core", "deps/grpc/src/boringssl", "deps/grpc/src/zlib", - "deps/grpc/third_party/nanopb", + "deps/grpc/third_party/nanopb/pb_common.c", + "deps/grpc/third_party/nanopb/pb_decode.c", + "deps/grpc/third_party/nanopb/pb_encode.c", "deps/grpc/third_party/zlib", - "deps/grpc/third_party/boringssl", + "deps/grpc/third_party/boringssl/crypto", + "deps/grpc/third_party/boringssl/include", + "deps/grpc/third_party/boringssl/ssl", "binding.gyp" ], "main": "index.js", diff --git a/packages/grpc-native-core/templates/package.json.template b/packages/grpc-native-core/templates/package.json.template index 45f52240..263e7484 100644 --- a/packages/grpc-native-core/templates/package.json.template +++ b/packages/grpc-native-core/templates/package.json.template @@ -66,7 +66,6 @@ "files": [ "LICENSE", "README.md", - "deps/grpc/src/proto", "deps/grpc/etc", "index.js", "src", @@ -75,9 +74,13 @@ "deps/grpc/src/core", "deps/grpc/src/boringssl", "deps/grpc/src/zlib", - "deps/grpc/third_party/nanopb", + "deps/grpc/third_party/nanopb/pb_common.c", + "deps/grpc/third_party/nanopb/pb_decode.c", + "deps/grpc/third_party/nanopb/pb_encode.c", "deps/grpc/third_party/zlib", - "deps/grpc/third_party/boringssl", + "deps/grpc/third_party/boringssl/crypto", + "deps/grpc/third_party/boringssl/include", + "deps/grpc/third_party/boringssl/ssl", "binding.gyp" ], "main": "index.js", From 3ecb385366495df4e06c34e818d88c1eab213af4 Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Tue, 19 Sep 2017 13:03:58 -0700 Subject: [PATCH 02/20] Change package.json file list to globs for granularity --- packages/grpc-native-core/package.json | 27 +++++++++---------- .../templates/package.json.template | 25 ++++++++--------- 2 files changed, 24 insertions(+), 28 deletions(-) diff --git a/packages/grpc-native-core/package.json b/packages/grpc-native-core/package.json index dd8e75f6..4baa04da 100644 --- a/packages/grpc-native-core/package.json +++ b/packages/grpc-native-core/package.json @@ -45,7 +45,9 @@ "google-protobuf": "^3.0.0", "istanbul": "^0.4.4", "jsdoc": "^3.3.2", + "jshint": "^2.5.0", "minimist": "^1.1.0", + "mocha": "^3.0.2", "mocha-jenkins-reporter": "^0.2.3", "poisson-process": "^0.2.1" }, @@ -62,21 +64,18 @@ "files": [ "LICENSE", "README.md", - "deps/grpc/etc", + "deps/grpc/etc/", "index.js", - "src", - "ext", - "deps/grpc/include/grpc", - "deps/grpc/src/core", - "deps/grpc/src/boringssl", - "deps/grpc/src/zlib", - "deps/grpc/third_party/nanopb/pb_common.c", - "deps/grpc/third_party/nanopb/pb_decode.c", - "deps/grpc/third_party/nanopb/pb_encode.c", - "deps/grpc/third_party/zlib", - "deps/grpc/third_party/boringssl/crypto", - "deps/grpc/third_party/boringssl/include", - "deps/grpc/third_party/boringssl/ssl", + "src/*.js", + "ext/*.{cc,h}", + "deps/grpc/include/grpc/**/*.h", + "deps/grpc/src/core/**/*.{c,h}", + "deps/grpc/src/boringssl/*.{c,h}", + "deps/grpc/third_party/nanopb/*.{c,h}", + "deps/grpc/third_party/zlib/**/*.{c,h}", + "deps/grpc/third_party/boringssl/crypto/**/*.{c,h}", + "deps/grpc/third_party/boringssl/include/**/*.{c,h}", + "deps/grpc/third_party/boringssl/ssl/**/*.{c,h}", "binding.gyp" ], "main": "index.js", diff --git a/packages/grpc-native-core/templates/package.json.template b/packages/grpc-native-core/templates/package.json.template index 263e7484..034eb5f4 100644 --- a/packages/grpc-native-core/templates/package.json.template +++ b/packages/grpc-native-core/templates/package.json.template @@ -66,21 +66,18 @@ "files": [ "LICENSE", "README.md", - "deps/grpc/etc", + "deps/grpc/etc/", "index.js", - "src", - "ext", - "deps/grpc/include/grpc", - "deps/grpc/src/core", - "deps/grpc/src/boringssl", - "deps/grpc/src/zlib", - "deps/grpc/third_party/nanopb/pb_common.c", - "deps/grpc/third_party/nanopb/pb_decode.c", - "deps/grpc/third_party/nanopb/pb_encode.c", - "deps/grpc/third_party/zlib", - "deps/grpc/third_party/boringssl/crypto", - "deps/grpc/third_party/boringssl/include", - "deps/grpc/third_party/boringssl/ssl", + "src/*.js", + "ext/*.{cc,h}", + "deps/grpc/include/grpc/**/*.h", + "deps/grpc/src/core/**/*.{c,h}", + "deps/grpc/src/boringssl/*.{c,h}", + "deps/grpc/third_party/nanopb/*.{c,h}", + "deps/grpc/third_party/zlib/**/*.{c,h}", + "deps/grpc/third_party/boringssl/crypto/**/*.{c,h}", + "deps/grpc/third_party/boringssl/include/**/*.{c,h}", + "deps/grpc/third_party/boringssl/ssl/**/*.{c,h}", "binding.gyp" ], "main": "index.js", From 62d71048fe26eade2e37b0f985971fc446f6626b Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Wed, 20 Sep 2017 12:39:16 -0700 Subject: [PATCH 03/20] Move dependencies around, add gulp target for document generation --- gulpfile.js | 4 ++- package.json | 14 +++-------- packages/grpc-native-core/gulpfile.js | 7 ++++++ packages/grpc-native-core/jsdoc_conf.json | 8 +----- packages/grpc-native-core/package.json | 12 +-------- .../templates/package.json.template | 15 +---------- test/gulpfile.js | 5 ++++ test/package.json | 25 +++++++++++++++++++ 8 files changed, 47 insertions(+), 43 deletions(-) create mode 100644 test/package.json diff --git a/gulpfile.js b/gulpfile.js index 2024412a..b31cc3c8 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -12,7 +12,7 @@ require('./test/gulpfile'); const root = __dirname; gulp.task('install.all', 'Install dependencies for all subdirectory packages', - ['js.core.install', 'native.core.install', 'health-check.install']); + ['js.core.install', 'native.core.install', 'health-check.install', 'internal.test.install']); gulp.task('lint', 'Emit linting errors in source and test files', ['js.core.lint', 'native.core.lint']); @@ -52,4 +52,6 @@ gulp.task('test', 'Run all tests', ['build'], () => { gulp.start('test.only'); }); +gulp.task('doc.gen', 'Generate documentation', ['native.core.doc.gen']); + gulp.task('default', ['help']); diff --git a/package.json b/package.json index f8aaf17b..8c23ea19 100644 --- a/package.json +++ b/package.json @@ -8,29 +8,23 @@ "name": "Google Inc." }, "license": "Apache-2.0", - "dependencies": { - "async": "^2.5.0", - "body-parser": "^1.18.0", - "execa": "^0.8.0", - "express": "^4.15.4", - "google-auth-library": "^0.11.0", - "lodash": "^4.17.4", - "mocha-jenkins-reporter": "^0.3.9", - "poisson-process": "^0.2.2" - }, "devDependencies": { "del": "^3.0.0", + "execa": "^0.8.0", "gulp": "^3.9.1", "gulp-help": "^1.6.1", + "gulp-jsdoc3": "^1.0.1", "gulp-jshint": "^2.0.4", "gulp-mocha": "^4.3.1", "gulp-sourcemaps": "^2.6.1", "gulp-tslint": "^8.1.1", "gulp-typescript": "^3.2.2", "gulp-util": "^3.0.8", + "jsdoc": "^3.3.2", "jshint": "^2.9.5", "merge2": "^1.1.0", "mocha": "^3.5.3", + "mocha-jenkins-reporter": "^0.3.9", "through2": "^2.0.3", "tslint": "^5.5.0", "typescript": "^2.5.1" diff --git a/packages/grpc-native-core/gulpfile.js b/packages/grpc-native-core/gulpfile.js index 7d85cf5b..bb695c9d 100644 --- a/packages/grpc-native-core/gulpfile.js +++ b/packages/grpc-native-core/gulpfile.js @@ -4,6 +4,7 @@ const help = require('gulp-help'); // gulp-help monkeypatches tasks to have an additional description parameter const gulp = help(_gulp); +const jsdoc = require('gulp-jsdoc3'); const jshint = require('gulp-jshint'); const mocha = require('gulp-mocha'); const execa = require('execa'); @@ -47,3 +48,9 @@ gulp.task('native.core.build', 'Build native package', () => { gulp.task('native.core.test', 'Run all tests', ['native.core.build'], () => { return gulp.src(`${testDir}/*.js`).pipe(mocha({reporter: 'mocha-jenkins-reporter'})); }); + +gulp.task('native.core.doc.gen', 'Generate docs', (cb) => { + var config = require('./jsdoc_conf.json'); + gulp.src([`${nativeCoreDir}/README.md`, `${nativeCoreDir}/index.js`, `${srcDir}/*.js`], {read: false}) + .pipe(jsdoc(config, cb)); +}); diff --git a/packages/grpc-native-core/jsdoc_conf.json b/packages/grpc-native-core/jsdoc_conf.json index 2d967753..92de2990 100644 --- a/packages/grpc-native-core/jsdoc_conf.json +++ b/packages/grpc-native-core/jsdoc_conf.json @@ -2,14 +2,8 @@ "tags": { "allowUnknownTags": true }, - "source": { - "include": [ "src/node/index.js", "src/node/src" ], - "includePattern": "src/node/.+\\.js(doc)?$", - "excludePattern": "(^|\\/|\\\\)_" - }, "opts": { - "package": "package.json", - "readme": "src/node/README.md" + "destination": "docs/gen/native/core" }, "plugins": ["plugins/markdown"], "templates": { diff --git a/packages/grpc-native-core/package.json b/packages/grpc-native-core/package.json index 19828430..c01cc81e 100644 --- a/packages/grpc-native-core/package.json +++ b/packages/grpc-native-core/package.json @@ -19,10 +19,7 @@ "lib": "src/node/src" }, "scripts": { - "lint": "node ./node_modules/jshint/bin/jshint src test index.js --exclude-path=.jshintignore", - "test": "./node_modules/.bin/mocha test && npm run-script lint", "electron-build": "./node_modules/.bin/node-pre-gyp configure build --runtime=electron --disturl=https://atom.io/download/atom-shell", - "gen_docs": "./node_modules/.bin/jsdoc -c jsdoc_conf.json", "coverage": "./node_modules/.bin/istanbul cover ./node_modules/.bin/_mocha test", "install": "./node_modules/.bin/node-pre-gyp install --fallback-to-build --library=static_library" }, @@ -37,16 +34,9 @@ "protobufjs": "^5.0.0" }, "devDependencies": { - "async": "^2.0.1", - "body-parser": "^1.15.2", "electron-mocha": "^3.1.1", - "express": "^4.14.0", - "google-auth-library": "^0.9.2", "google-protobuf": "^3.0.0", - "istanbul": "^0.4.4", - "jsdoc": "^3.3.2", - "minimist": "^1.1.0", - "poisson-process": "^0.2.1" + "istanbul": "^0.4.4" }, "engines": { "node": ">=4" diff --git a/packages/grpc-native-core/templates/package.json.template b/packages/grpc-native-core/templates/package.json.template index 45f52240..0a5cd53e 100644 --- a/packages/grpc-native-core/templates/package.json.template +++ b/packages/grpc-native-core/templates/package.json.template @@ -21,10 +21,7 @@ "lib": "src/node/src" }, "scripts": { - "lint": "node ./node_modules/jshint/bin/jshint src test index.js --exclude-path=.jshintignore", - "test": "./node_modules/.bin/mocha test && npm run-script lint", "electron-build": "./node_modules/.bin/node-pre-gyp configure build --runtime=electron --disturl=https://atom.io/download/atom-shell", - "gen_docs": "./node_modules/.bin/jsdoc -c jsdoc_conf.json", "coverage": "./node_modules/.bin/istanbul cover ./node_modules/.bin/_mocha test", "install": "./node_modules/.bin/node-pre-gyp install --fallback-to-build --library=static_library" }, @@ -39,19 +36,9 @@ "protobufjs": "^5.0.0" }, "devDependencies": { - "async": "^2.0.1", - "body-parser": "^1.15.2", "electron-mocha": "^3.1.1", - "express": "^4.14.0", - "google-auth-library": "^0.9.2", "google-protobuf": "^3.0.0", - "istanbul": "^0.4.4", - "jsdoc": "^3.3.2", - "jshint": "^2.5.0", - "minimist": "^1.1.0", - "mocha": "^3.0.2", - "mocha-jenkins-reporter": "^0.2.3", - "poisson-process": "^0.2.1" + "istanbul": "^0.4.4" }, "engines": { "node": ">=4" diff --git a/test/gulpfile.js b/test/gulpfile.js index b66b6e01..64a5d059 100644 --- a/test/gulpfile.js +++ b/test/gulpfile.js @@ -15,6 +15,11 @@ gulp.task('internal.test.clean.links', 'Delete npm links', () => { return del(path.resolve(testDir, 'node_modules/grpc')); }); +gulp.task('internal.test.install', 'Install test dependencies', () => { + return execa('npm', ['install', '--build-from-source', '--unsafe-perm'], + {cwd: testDir, stdio: 'inherit'}); +}); + gulp.task('internal.test.clean.all', 'Delete all files created by tasks', ['internal.test.clean.links']); diff --git a/test/package.json b/test/package.json new file mode 100644 index 00000000..e987314c --- /dev/null +++ b/test/package.json @@ -0,0 +1,25 @@ +{ + "name": "grpc-node-test", + "version": "0.1.0", + "description": "Dummy package for the grpc-node repository tests", + "private": true, + "keywords": [], + "author": { + "name": "Google Inc." + }, + "license": "Apache-2.0", + "contributors": [ + { + "name": "Google Inc." + } + ], + "dependencies": { + "async": "^2.0.1", + "body-parser": "^1.15.2", + "express": "^4.14.0", + "google-auth-library": "^0.9.2", + "lodash": "^4.17.4", + "minimist": "^1.1.0", + "poisson-process": "^0.2.1" + } +} From f1fb87245d357677226dae0b792a9da6f27da49c Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Mon, 25 Sep 2017 14:48:02 -0700 Subject: [PATCH 04/20] Readded an npm script --- packages/grpc-native-core/package.json | 1 + packages/grpc-native-core/templates/package.json.template | 1 + 2 files changed, 2 insertions(+) diff --git a/packages/grpc-native-core/package.json b/packages/grpc-native-core/package.json index c01cc81e..1a6ecde0 100644 --- a/packages/grpc-native-core/package.json +++ b/packages/grpc-native-core/package.json @@ -19,6 +19,7 @@ "lib": "src/node/src" }, "scripts": { + "build": "./node_modules/.bin/node-pre-gyp build", "electron-build": "./node_modules/.bin/node-pre-gyp configure build --runtime=electron --disturl=https://atom.io/download/atom-shell", "coverage": "./node_modules/.bin/istanbul cover ./node_modules/.bin/_mocha test", "install": "./node_modules/.bin/node-pre-gyp install --fallback-to-build --library=static_library" diff --git a/packages/grpc-native-core/templates/package.json.template b/packages/grpc-native-core/templates/package.json.template index 0a5cd53e..fc188eaa 100644 --- a/packages/grpc-native-core/templates/package.json.template +++ b/packages/grpc-native-core/templates/package.json.template @@ -21,6 +21,7 @@ "lib": "src/node/src" }, "scripts": { + "build": "./node_modules/.bin/node-pre-gyp build", "electron-build": "./node_modules/.bin/node-pre-gyp configure build --runtime=electron --disturl=https://atom.io/download/atom-shell", "coverage": "./node_modules/.bin/istanbul cover ./node_modules/.bin/_mocha test", "install": "./node_modules/.bin/node-pre-gyp install --fallback-to-build --library=static_library" From f27449a076bf3bcf3ba5c573702193d478dc6561 Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Thu, 28 Sep 2017 17:13:02 -0700 Subject: [PATCH 05/20] Add missing gulp dependency, remove unnecessary flags from one task --- gulpfile.js | 2 +- test/gulpfile.js | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/gulpfile.js b/gulpfile.js index c808cdcf..f1a333e4 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -32,7 +32,7 @@ gulp.task('install.all', 'Install dependencies for all subdirectory packages', ['js.core.install', 'native.core.install', 'health-check.install', 'internal.test.install']); gulp.task('install.all.windows', 'Install dependencies for all subdirectory packages for MS Windows', - ['js.core.install', 'native.core.install.windows', 'health-check.install']); + ['js.core.install', 'native.core.install.windows', 'health-check.install', 'internal.test.install']); gulp.task('lint', 'Emit linting errors in source and test files', ['js.core.lint', 'native.core.lint']); diff --git a/test/gulpfile.js b/test/gulpfile.js index 326df8a4..469f8d23 100644 --- a/test/gulpfile.js +++ b/test/gulpfile.js @@ -33,8 +33,7 @@ gulp.task('internal.test.clean.links', 'Delete npm links', () => { }); gulp.task('internal.test.install', 'Install test dependencies', () => { - return execa('npm', ['install', '--build-from-source', '--unsafe-perm'], - {cwd: testDir, stdio: 'inherit'}); + return execa('npm', ['install'], {cwd: testDir, stdio: 'inherit'}); }); gulp.task('internal.test.clean.all', 'Delete all files created by tasks', From 1428315e3bac5c66b16ef7f9e7b6b373ed981de2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 29 Sep 2017 11:31:32 +0200 Subject: [PATCH 06/20] Add TypeScript typings to gRPC native core package --- packages/grpc-native-core/index.d.ts | 1214 ++++++++++++++++++++++++ packages/grpc-native-core/package.json | 1 + 2 files changed, 1215 insertions(+) create mode 100644 packages/grpc-native-core/index.d.ts diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts new file mode 100644 index 00000000..12e9bd5a --- /dev/null +++ b/packages/grpc-native-core/index.d.ts @@ -0,0 +1,1214 @@ +declare module "grpc" { + import { Service } from "protobufjs"; + + /** + * 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(value: object, options?: LoadObjectOptions): GrpcObject; + + /** + * 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 { + [namespace: string]: { + [service: string]: typeof Client, + }; + } + + /** + * 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(filename: Filename, format?: "proto" | "json", options?: LoadOptions): 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: number): 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(name: string, handler: handleCall, serialize: serialize, deserialize: deserialize, 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(service: Service, implementation: { [name: string]: handleCall }): 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(service: Service, implementation: { [name: string]: handleCall }): 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. + */ + bind(port: string, creds: ServerCredentials): void; + } + + /** + * An object that completely defines a service. + * @typedef {Object.} grpc~ServiceDefinition + */ + export interface ServiceDefinition { + [s: string]: MethodDefinition; + } + + /** + * An object that completely defines a service method signature. + */ + export interface MethodDefinition { + /** + * 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; + /** + * Serialization function for response values + */ + responseSerialize: serialize; + /** + * Deserialization function for request data + */ + requestDeserialize: deserialize; + /** + * Deserialization function for repsonse data + */ + responseDeserialize: deserialize; + } + + type handleCall = handleUnaryCall | handleClientStreamingCall | handleServerStreamingCall | handleBidiStreamingCall; + + /** + * User-provided method to handle unary requests on a server + */ + type handleUnaryCall = (call: ServerUnaryCall, callback: sendUnaryData) => void; + + export class ServerUnaryCall { + /** + * Indicates if the call has been cancelled + */ + cancelled: boolean; + + /** + * The request metadata from the client + */ + metadata: Metadata; + + /** + * The request message from the client + */ + request: any; + + /** + * An EventEmitter. Used for unary calls. + * @param call The call object associated with the request + * @param metadata The request metadata from the client + */ + constructor(call: Call, metadata: Metadata); + + /** + * 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 = (call: ServerReadableStream, callback: sendUnaryData) => void; + + export class ServerReadableStream { + /** + * Indicates if the call has been cancelled + */ + cancelled: boolean; + + /** + * The request metadata from the client + */ + metadata: Metadata; + + /** + * A stream that the server can read from. Used for calls that are streaming + * from the client side. + * @param call The call object to read data with + * @param metadata The request metadata from the client + * @param deserialize Deserialization function for reads + */ + constructor(call: Call, metadata: Metadata, deserialize: deserialize); + + /** + * 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 = (call: ServerWriteableStream) => void; + + export class ServerWriteableStream { + /** + * Indicates if the call has been cancelled + */ + cancelled: boolean; + + /** + * The request metadata from the client + */ + metadata: Metadata; + + /** + * The request message from the client + */ + request: any; + + /** + * A stream that the server can write to. Used for calls that are streaming + * from the server side. + * @param call The call object to send data with + * @param metadata The request metadata from the client + * @param serialize Serialization function for writes + */ + constructor(call: Call, metadata: Metadata, serialize: serialize); + + /** + * 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 = (call: ServerDuplexStream) => void; + + export class ServerDuplexStream { + /** + * A stream that the server can read from or write to. Used for calls + * with duplex streaming. + * @param call Call object to proxy + * @param metadata The request metadata from the client + * @param serialize Serialization function for requests + * @param deserialize Deserialization function for requests + */ + constructor(call: any, metadata: Metadata, serialize: serialize, deserialize: deserialize); + + /** + * 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 = (data: Buffer) => any; + + /** + * A serialization function + * @param value The value to serialize + * @return The value serialized as a byte sequence + */ + type serialize = (value: any) => Buffer; + + /** + * Callback function passed to server handlers that handle methods with + * unary responses. + */ + type sendUnaryData = (error: ServiceError | null, value: any, trailer?: Metadata, flags?: number) => void; + + export class Metadata { + /** + * Class for storing metadata. Keys are normalized to lowercase ASCII. + * ``` + * var metadata = new metadata_module.Metadata(); + * metadata.set('key1', 'value1'); + * metadata.add('key1', 'value2'); + * metadata.get('key1') // returns ['value1', 'value2'] + * ``` + */ + constructor(); + + /** + * Sets the given value for the given key, replacing any other values associated + * with that key. Normalizes the key. + * @param key The key to 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: string | Buffer): void; + + /** + * Adds the given value for the given key. Normalizes the key. + * @param key The key to add to. + * @param value The value to add. Must be a buffer if and only + * if the normalized key ends with '-bin' + */ + add(key: string, value: string | Buffer): void; + + /** + * Remove the given key and any associated values. Normalizes the key. + * @param key The key to remove + */ + remove(key: string): void; + + /** + * Gets a list of all values associated with the key. Normalizes the key. + * @param key The key to get + * @return The values associated with that key + */ + get(key: string): Array; + + /** + * Get a map of each key to a single associated value. This reflects the most + * common way that people will want to see metadata. + * @return A key/value mapping of the metadata + */ + getMap(): { [index: string]: string | Buffer }; + + /** + * Clone the metadata object. + * @return {Metadata} The new cloned object + */ + clone(): Metadata; + } + + /** + * 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: number; + /** + * 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 class ServiceError extends Error { + /** + * The error code, a key of {@link grpc.status} that is not `grpc.status.OK` + */ + code: number; + /** + * 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 createInsecure(rootCerts: Buffer | null, keyCertPairs: KeyCertPair[], checkClientCertificate?: boolean): ServerCredentials; + } + + /** + * A private key and certificate pair + */ + export interface KeyCertPair { + /** + * The server's private key + */ + privateKey: Buffer; + + /** + * The server's certificate chain + */ + certChain: 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 genrally 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: GoogleCredential): 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 class ChannelCredentials {} + + /** + * This cannot be constructed directly. Instead, instances of this class should + * be created using the factory functions in `grpc.credentials` + */ + export class CallCredentials {} + + /** + * Google credential from https://github.com/google/google-auth-library-nodejs lib. + * The object definition is copied from `ts/lib/auth/credentials.ts` + */ + export interface GoogleCredential { + refresh_token?: string; + expiry_date?: number; + access_token?: string; + token_type?: string; + } + + /** + * 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, + 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 {Object} 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( + method: string, + serialize: serialize, + deserialize: deserialize, + argument: any | null, + metadata: Metadata | null, + options: CallOptions | null, + callback: requestCallback, + ): 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( + method: string, + serialize: serialize, + deserialize: deserialize, + metadata: Metadata | null, + options: CallOptions | null, + callback: requestCallback, + ): ClientWritableStream; + + /** + * 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( + method: string, + serialize: serialize, + deserialize: deserialize, + argument: any, + metadata?: Metadata | null, + options?: CallOptions | null, + ): ClientReadableStream; + + /** + * 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( + method: string, + serialize: serialize, + deserialize: deserialize, + metadata?: Metadata | null, + options?: CallOptions | null, + ): ClientDuplexStream; + + /** + * 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 | ClientWritableStream | ClientDuplexStream; + + export class ClientUnaryCall { + /** + * An EventEmitter. Used for unary calls. + * @param call The call object associated with the request + */ + constructor(call: any); + + /** + * 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; + } + + export class ClientReadableStream { + /** + * A stream that the client can read from. Used for calls that are streaming + * from the server side. + * @param call The call object to read data with + * @param deserialize Deserialization function for reads. Defaults to `identity`. + */ + constructor(call: any, deserialize?: deserialize); + + /** + * 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; + } + + export class ClientWritableStream { + /** + * A stream that the client can write to. Used for calls that are streaming from + * the client side. + * @param call The call object to send data with + * @param serialize Serialization + * function for writes. Defaults to `identity`. + */ + constructor(call: any, serialize?: serialize); + + /** + * 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: any, flags: 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; + } + + export class ClientDuplexStream { + /** + * A stream that the client can read from or write to. Used for calls with + * duplex streaming. + * @param {grpc.internal~Call} call Call object to proxy + * @param serialize Serialization function for requests. Defaults to `identity`. + * @param deserialize Deserialization function for responses. Defaults to `identity`. + */ + constructor(call: any, serialize?: serialize | null, deserialize?: deserialize | null); + + /** + * 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: any, flags: 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 = (error: Error | null, value: any) => 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 unrecoverablly + * 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; +} diff --git a/packages/grpc-native-core/package.json b/packages/grpc-native-core/package.json index 4a0c220d..90acad8c 100644 --- a/packages/grpc-native-core/package.json +++ b/packages/grpc-native-core/package.json @@ -67,6 +67,7 @@ "binding.gyp" ], "main": "index.js", + "typings": "src/index.d.ts", "license": "Apache-2.0", "jshintConfig": { "bitwise": true, From 6cde0631e816a83e69871ee8da30b8a9ebf4f603 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 29 Sep 2017 13:58:28 +0200 Subject: [PATCH 07/20] Typos fixed --- packages/grpc-native-core/index.js | 2 +- packages/grpc-native-core/src/client.js | 2 +- packages/grpc-native-core/src/constants.js | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/packages/grpc-native-core/index.js b/packages/grpc-native-core/index.js index 0d814cc3..ca056b3a 100644 --- a/packages/grpc-native-core/index.js +++ b/packages/grpc-native-core/index.js @@ -67,7 +67,7 @@ grpc.setDefaultRootsPem(fs.readFileSync(SSL_ROOTS_PATH, 'ascii')); * @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 wll guess what the version is based on the structure of the value. + * gRPC will guess what the version is based on the structure of the value. * @return {Object} The resulting gRPC object. */ exports.loadObject = function loadObject(value, options) { diff --git a/packages/grpc-native-core/src/client.js b/packages/grpc-native-core/src/client.js index d3c39ca4..7c5c418e 100644 --- a/packages/grpc-native-core/src/client.js +++ b/packages/grpc-native-core/src/client.js @@ -929,7 +929,7 @@ exports.makeClientConstructor = function(methods, serviceName, * Return the underlying channel object for the specified client * @memberof grpc * @alias grpc~getClientChannel - * @param {Client} client + * @param {Client} client The client * @return {Channel} The channel * @see grpc.Client#getChannel */ diff --git a/packages/grpc-native-core/src/constants.js b/packages/grpc-native-core/src/constants.js index c90e44d0..b91d4214 100644 --- a/packages/grpc-native-core/src/constants.js +++ b/packages/grpc-native-core/src/constants.js @@ -139,7 +139,8 @@ exports.status = { * a backoff. * * See litmus test above for deciding between FAILED_PRECONDITION, - * ABORTED, and UNAVAILABLE. */ + * ABORTED, and UNAVAILABLE. + */ UNAVAILABLE: 14, /** Unrecoverable data loss or corruption. */ DATA_LOSS: 15, @@ -150,7 +151,7 @@ exports.status = { UNAUTHENTICATED: 16 }; -/* The comments about propagation bit flags are copied rom +/* The comments about propagation bit flags are copied from * include/grpc/impl/codegen/propagation_bits.h for the purpose of including * them in generated documentation. */ From f14785628796047b9f67bbc8abe74c1538f24950 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 29 Sep 2017 14:17:11 +0200 Subject: [PATCH 08/20] Fix type links --- packages/grpc-native-core/index.js | 4 ++-- packages/grpc-native-core/src/client.js | 10 +++++----- packages/grpc-native-core/src/common.js | 2 +- packages/grpc-native-core/src/credentials.js | 18 +++++++++--------- packages/grpc-native-core/src/metadata.js | 2 +- packages/grpc-native-core/src/server.js | 2 +- 6 files changed, 19 insertions(+), 19 deletions(-) diff --git a/packages/grpc-native-core/index.js b/packages/grpc-native-core/index.js index ca056b3a..af597f70 100644 --- a/packages/grpc-native-core/index.js +++ b/packages/grpc-native-core/index.js @@ -213,7 +213,7 @@ exports.ServerCredentials = grpc.ServerCredentials; * Create insecure server credentials * @name grpc.ServerCredentials.createInsecure * @kind function - * @return grpc.ServerCredentials + * @return {grpc.ServerCredentials} */ /** @@ -234,7 +234,7 @@ exports.ServerCredentials = grpc.ServerCredentials; * the server * @param {boolean} [checkClientCertificate=false] Indicates that the server * should request and verify the client's certificates - * @return grpc.ServerCredentials + * @return {grpc.ServerCredentials} */ exports.makeGenericClientConstructor = client.makeClientConstructor; diff --git a/packages/grpc-native-core/src/client.js b/packages/grpc-native-core/src/client.js index 7c5c418e..24af23b8 100644 --- a/packages/grpc-native-core/src/client.js +++ b/packages/grpc-native-core/src/client.js @@ -393,8 +393,8 @@ ClientDuplexStream.prototype.getPeer = getPeer; /** * Any client call type - * @typedef {(ClientUnaryCall|ClientReadableStream| - * ClientWritableStream|ClientDuplexStream)} + * @typedef {(grpc~ClientUnaryCall|grpc~ClientReadableStream| + * grpc~ClientWritableStream|grpc~ClientDuplexStream)} * grpc.Client~Call */ @@ -450,7 +450,7 @@ function getCall(channel, method, options) { * @memberof grpc * @constructor * @param {string} address Server address to connect to - * @param {grpc~ChannelCredentials} credentials Credentials to use to connect to + * @param {grpc.credentials~ChannelCredentials} credentials Credentials to use to connect to * the server * @param {Object} options Options to apply to channel creation */ @@ -929,7 +929,7 @@ exports.makeClientConstructor = function(methods, serviceName, * Return the underlying channel object for the specified client * @memberof grpc * @alias grpc~getClientChannel - * @param {Client} client The client + * @param {grpc.Client} client The client * @return {Channel} The channel * @see grpc.Client#getChannel */ @@ -945,7 +945,7 @@ exports.getClientChannel = function(client) { * start connecting if it has not already done so. * @memberof grpc * @alias grpc~waitForClientReady - * @param {Client} client The client to wait on + * @param {grpc.Client} client The client to wait on * @param {grpc~Deadline} deadline When to stop waiting for a connection. Pass * Infinity to wait forever. * @param {function(Error)} callback The callback to call when done attempting diff --git a/packages/grpc-native-core/src/common.js b/packages/grpc-native-core/src/common.js index 5a444f5e..5882cf1c 100644 --- a/packages/grpc-native-core/src/common.js +++ b/packages/grpc-native-core/src/common.js @@ -145,7 +145,7 @@ exports.defaultGrpcOptions = { * 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. - * @typedef {(number|date)} grpc~Deadline + * @typedef {(number|Date)} grpc~Deadline */ /** diff --git a/packages/grpc-native-core/src/credentials.js b/packages/grpc-native-core/src/credentials.js index d68d888e..a2312966 100644 --- a/packages/grpc-native-core/src/credentials.js +++ b/packages/grpc-native-core/src/credentials.js @@ -86,7 +86,7 @@ var _ = require('lodash'); * @param {Buffer=} private_key The client certificate private key, if * applicable * @param {Buffer=} cert_chain The client certificate cert chain, if applicable - * @return {grpc.credentials.ChannelCredentials} The SSL Credentials object + * @return {grpc.credentials~ChannelCredentials} The SSL Credentials object */ exports.createSsl = ChannelCredentials.createSsl; @@ -113,7 +113,7 @@ exports.createSsl = ChannelCredentials.createSsl; * @alias grpc.credentials.createFromMetadataGenerator * @param {grpc.credentials~generateMetadata} metadata_generator The function * that generates metadata - * @return {grpc.credentials.CallCredentials} The credentials object + * @return {grpc.credentials~CallCredentials} The credentials object */ exports.createFromMetadataGenerator = function(metadata_generator) { return CallCredentials.createFromPlugin(function(service_url, cb_data, @@ -143,7 +143,7 @@ exports.createFromMetadataGenerator = function(metadata_generator) { * @alias grpc.credentials.createFromGoogleCredential * @param {external:GoogleCredential} google_credential The Google credential * object to use - * @return {grpc.credentials.CallCredentials} The resulting credentials object + * @return {grpc.credentials~CallCredentials} The resulting credentials object */ exports.createFromGoogleCredential = function(google_credential) { return exports.createFromMetadataGenerator(function(auth_context, callback) { @@ -166,10 +166,10 @@ exports.createFromGoogleCredential = function(google_credential) { * ChannelCredentials object. * @memberof grpc.credentials * @alias grpc.credentials.combineChannelCredentials - * @param {ChannelCredentials} channel_credential The ChannelCredentials to + * @param {grpc.credentials~ChannelCredentials} channel_credential The ChannelCredentials to * start with - * @param {...CallCredentials} credentials The CallCredentials to compose - * @return ChannelCredentials A credentials object that combines all of the + * @param {...grpc.credentials~CallCredentials} credentials The CallCredentials to compose + * @return {grpc.credentials~ChannelCredentials} A credentials object that combines all of the * input credentials */ exports.combineChannelCredentials = function(channel_credential) { @@ -184,8 +184,8 @@ exports.combineChannelCredentials = function(channel_credential) { * Combine any number of CallCredentials into a single CallCredentials object * @memberof grpc.credentials * @alias grpc.credentials.combineCallCredentials - * @param {...CallCredentials} credentials the CallCredentials to compose - * @return CallCredentials A credentials object that combines all of the input + * @param {...grpc.credentials~CallCredentials} credentials The CallCredentials to compose + * @return {grpc.credentials~CallCredentials} A credentials object that combines all of the input * credentials */ exports.combineCallCredentials = function() { @@ -202,6 +202,6 @@ exports.combineCallCredentials = function() { * @memberof grpc.credentials * @alias grpc.credentials.createInsecure * @kind function - * @return {ChannelCredentials} The insecure credentials object + * @return {grpc.credentials~ChannelCredentials} The insecure credentials object */ exports.createInsecure = ChannelCredentials.createInsecure; diff --git a/packages/grpc-native-core/src/metadata.js b/packages/grpc-native-core/src/metadata.js index 46f9e0fe..63bbed76 100644 --- a/packages/grpc-native-core/src/metadata.js +++ b/packages/grpc-native-core/src/metadata.js @@ -132,7 +132,7 @@ Metadata.prototype.getMap = function() { /** * Clone the metadata object. - * @return {Metadata} The new cloned object + * @return {grpc.Metadata} The new cloned object */ Metadata.prototype.clone = function() { var copy = new Metadata(); diff --git a/packages/grpc-native-core/src/server.js b/packages/grpc-native-core/src/server.js index 8b7c0b68..cee852e9 100644 --- a/packages/grpc-native-core/src/server.js +++ b/packages/grpc-native-core/src/server.js @@ -470,7 +470,7 @@ ServerDuplexStream.prototype._write = _write; /** * Send the initial metadata for a writable stream. * @alias grpc~ServerUnaryCall#sendMetadata - * @param {Metadata} responseMetadata Metadata to send + * @param {grpc.Metadata} responseMetadata Metadata to send */ function sendMetadata(responseMetadata) { /* jshint validthis: true */ From bdbbd5324956a118dacf21380a5e3d9eac6be62e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 29 Sep 2017 20:39:56 +0200 Subject: [PATCH 09/20] Remove wrongly encoded spaces --- packages/grpc-native-core/index.d.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index 12e9bd5a..c4f03b51 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -428,7 +428,7 @@ declare module "grpc" { * Callback function passed to server handlers that handle methods with * unary responses. */ - type sendUnaryData = (error: ServiceError | null, value: any, trailer?: Metadata, flags?: number) => void; + type sendUnaryData = (error: ServiceError | null, value: any, trailer?: Metadata, flags?: number) => void; export class Metadata { /** @@ -930,7 +930,7 @@ declare module "grpc" { serialize: serialize, deserialize: deserialize, argument: any | null, - metadata: Metadata | null, + metadata: Metadata | null, options: CallOptions | null, callback: requestCallback, ): ClientUnaryCall; @@ -1015,7 +1015,7 @@ declare module "grpc" { * @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; + waitForReady(deadline: Deadline, callback: (error: Error | null) => void): void; } /** @@ -1151,7 +1151,7 @@ declare module "grpc" { * @param serialize Serialization function for requests. Defaults to `identity`. * @param deserialize Deserialization function for responses. Defaults to `identity`. */ - constructor(call: any, serialize?: serialize | null, deserialize?: deserialize | null); + constructor(call: any, serialize?: serialize | null, deserialize?: deserialize | null); /** * Write a message to the request stream. If serializing the argument fails, From 4cbf7572b530d9c13647f85d0142fe52f369c7fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Sun, 1 Oct 2017 10:33:48 +0200 Subject: [PATCH 10/20] Changes based on review. --- packages/grpc-native-core/index.d.ts | 112 +++++++++------------------ 1 file changed, 37 insertions(+), 75 deletions(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index c4f03b51..ee365527 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -1,5 +1,5 @@ declare module "grpc" { - import { Service } from "protobufjs"; + import { Message, Service } from "protobufjs"; /** * Load a ProtoBuf.js object as a gRPC object. @@ -64,9 +64,7 @@ declare module "grpc" { * - Anything else becomes the relevant reflection object that ProtoBuf.js would create */ export interface GrpcObject { - [namespace: string]: { - [service: string]: typeof Client, - }; + [name: string]: GrpcObject | typeof Client | Message; } /** @@ -130,7 +128,7 @@ declare module "grpc" { * of the grpc.logVerbosity map. * @param verbosity The minimum severity to log */ - export function setLogVerbosity(verbosity: number): void; + export function setLogVerbosity(verbosity: logVerbosity): void; /** * Server object that stores request handlers and delegates incoming requests to those handlers @@ -202,7 +200,7 @@ declare module "grpc" { * @param implementation Map of method names to method implementation * for the provided service. */ - addProtoService(service: Service, implementation: { [name: string]: handleCall }): void; + addProtoService(service: Service | ServiceDefinition, implementation: { [name: string]: handleCall }): void; /** * Binds the server to the given port, with SSL disabled if creds is an @@ -211,8 +209,9 @@ declare module "grpc" { * "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): void; + bind(port: string, creds: ServerCredentials): number; } /** @@ -264,6 +263,9 @@ declare module "grpc" { */ type handleUnaryCall = (call: ServerUnaryCall, callback: sendUnaryData) => void; + /** + * An EventEmitter. Used for unary calls. + */ export class ServerUnaryCall { /** * Indicates if the call has been cancelled @@ -280,13 +282,6 @@ declare module "grpc" { */ request: any; - /** - * An EventEmitter. Used for unary calls. - * @param call The call object associated with the request - * @param metadata The request metadata from the client - */ - constructor(call: Call, metadata: Metadata); - /** * Get the endpoint this call/stream is connected to. * @return The URI of the endpoint @@ -305,6 +300,10 @@ declare module "grpc" { */ type handleClientStreamingCall = (call: ServerReadableStream, callback: sendUnaryData) => void; + /** + * A stream that the server can read from. Used for calls that are streaming + * from the client side. + */ export class ServerReadableStream { /** * Indicates if the call has been cancelled @@ -316,15 +315,6 @@ declare module "grpc" { */ metadata: Metadata; - /** - * A stream that the server can read from. Used for calls that are streaming - * from the client side. - * @param call The call object to read data with - * @param metadata The request metadata from the client - * @param deserialize Deserialization function for reads - */ - constructor(call: Call, metadata: Metadata, deserialize: deserialize); - /** * Get the endpoint this call/stream is connected to. * @return The URI of the endpoint @@ -343,6 +333,10 @@ declare module "grpc" { */ type handleServerStreamingCall = (call: ServerWriteableStream) => void; + /** + * A stream that the server can write to. Used for calls that are streaming + * from the server side. + */ export class ServerWriteableStream { /** * Indicates if the call has been cancelled @@ -359,15 +353,6 @@ declare module "grpc" { */ request: any; - /** - * A stream that the server can write to. Used for calls that are streaming - * from the server side. - * @param call The call object to send data with - * @param metadata The request metadata from the client - * @param serialize Serialization function for writes - */ - constructor(call: Call, metadata: Metadata, serialize: serialize); - /** * Get the endpoint this call/stream is connected to. * @return The URI of the endpoint @@ -386,17 +371,11 @@ declare module "grpc" { */ type handleBidiStreamingCall = (call: ServerDuplexStream) => void; + /** + * A stream that the server can read from or write to. Used for calls + * with duplex streaming. + */ export class ServerDuplexStream { - /** - * A stream that the server can read from or write to. Used for calls - * with duplex streaming. - * @param call Call object to proxy - * @param metadata The request metadata from the client - * @param serialize Serialization function for requests - * @param deserialize Deserialization function for requests - */ - constructor(call: any, metadata: Metadata, serialize: serialize, deserialize: deserialize); - /** * Get the endpoint this call/stream is connected to. * @return The URI of the endpoint @@ -517,7 +496,7 @@ declare module "grpc" { /** * The error code, a key of {@link grpc.status} that is not `grpc.status.OK` */ - code: number; + code: status; /** * Trailing metadata sent with the status, if applicable */ @@ -1067,13 +1046,10 @@ declare module "grpc" { */ type Call = ClientUnaryCall | ClientReadableStream | ClientWritableStream | ClientDuplexStream; + /** + * An EventEmitter. Used for unary calls. + */ export class ClientUnaryCall { - /** - * An EventEmitter. Used for unary calls. - * @param call The call object associated with the request - */ - constructor(call: any); - /** * Cancel the ongoing call. Results in the call ending with a CANCELLED status, * unless it has already ended with some other status. @@ -1087,15 +1063,11 @@ declare module "grpc" { getPeer(): string; } + /** + * A stream that the client can read from. Used for calls that are streaming + * from the server side. + */ export class ClientReadableStream { - /** - * A stream that the client can read from. Used for calls that are streaming - * from the server side. - * @param call The call object to read data with - * @param deserialize Deserialization function for reads. Defaults to `identity`. - */ - constructor(call: any, deserialize?: deserialize); - /** * Cancel the ongoing call. Results in the call ending with a CANCELLED status, * unless it has already ended with some other status. @@ -1109,16 +1081,11 @@ declare module "grpc" { getPeer(): string; } + /** + * A stream that the client can write to. Used for calls that are streaming from + * the client side. + */ export class ClientWritableStream { - /** - * A stream that the client can write to. Used for calls that are streaming from - * the client side. - * @param call The call object to send data with - * @param serialize Serialization - * function for writes. Defaults to `identity`. - */ - constructor(call: any, serialize?: serialize); - /** * 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. @@ -1143,16 +1110,11 @@ declare module "grpc" { getPeer(): string; } + /** + * A stream that the client can read from or write to. Used for calls with + * duplex streaming. + */ export class ClientDuplexStream { - /** - * A stream that the client can read from or write to. Used for calls with - * duplex streaming. - * @param {grpc.internal~Call} call Call object to proxy - * @param serialize Serialization function for requests. Defaults to `identity`. - * @param deserialize Deserialization function for responses. Defaults to `identity`. - */ - constructor(call: any, serialize?: serialize | null, deserialize?: deserialize | null); - /** * 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. From cd265999f3aba31dbfba150a9e49cf436d268900 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Sun, 1 Oct 2017 10:35:22 +0200 Subject: [PATCH 11/20] Missed a status code enum --- packages/grpc-native-core/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index ee365527..f2c014d2 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -476,7 +476,7 @@ declare module "grpc" { /** * The error code, a key of `grpc.status` */ - code: number; + code: status; /** * Human-readable description of the status */ From d0218f21b6595bdfc58f3d0bc1ff18b97c934e18 Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Mon, 2 Oct 2017 13:49:05 -0700 Subject: [PATCH 12/20] Update grpc submodule --- packages/grpc-native-core/binding.gyp | 2 ++ packages/grpc-native-core/deps/grpc | 2 +- packages/grpc-native-core/ext/call_credentials.cc | 11 ++++++++--- packages/grpc-native-core/ext/call_credentials.h | 10 +++++++--- 4 files changed, 18 insertions(+), 7 deletions(-) diff --git a/packages/grpc-native-core/binding.gyp b/packages/grpc-native-core/binding.gyp index 861ac0af..f35bd619 100644 --- a/packages/grpc-native-core/binding.gyp +++ b/packages/grpc-native-core/binding.gyp @@ -670,6 +670,8 @@ 'deps/grpc/src/core/lib/compression/compression.c', 'deps/grpc/src/core/lib/compression/message_compress.c', 'deps/grpc/src/core/lib/compression/stream_compression.c', + 'deps/grpc/src/core/lib/compression/stream_compression_gzip.c', + 'deps/grpc/src/core/lib/compression/stream_compression_identity.c', 'deps/grpc/src/core/lib/debug/stats.c', 'deps/grpc/src/core/lib/debug/stats_data.c', 'deps/grpc/src/core/lib/http/format_request.c', diff --git a/packages/grpc-native-core/deps/grpc b/packages/grpc-native-core/deps/grpc index cbe93839..8d1dc219 160000 --- a/packages/grpc-native-core/deps/grpc +++ b/packages/grpc-native-core/deps/grpc @@ -1 +1 @@ -Subproject commit cbe93839937e4e6272407ab1b7ae7ef848b64894 +Subproject commit 8d1dc21994b2c8d4600db706b60b300c1a5a24a7 diff --git a/packages/grpc-native-core/ext/call_credentials.cc b/packages/grpc-native-core/ext/call_credentials.cc index 4cf3e565..2b1cb35f 100644 --- a/packages/grpc-native-core/ext/call_credentials.cc +++ b/packages/grpc-native-core/ext/call_credentials.cc @@ -238,9 +238,13 @@ NAUV_WORK_CB(SendPluginCallback) { } } -void plugin_get_metadata(void *state, grpc_auth_metadata_context context, - grpc_credentials_plugin_metadata_cb cb, - void *user_data) { +int plugin_get_metadata( + void *state, grpc_auth_metadata_context context, + grpc_credentials_plugin_metadata_cb cb, + void *user_data, + grpc_metadata creds_md[GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX], + size_t *num_creds_md, grpc_status_code *status, + const char **error_details) { plugin_state *p_state = reinterpret_cast(state); plugin_callback_data *data = new plugin_callback_data; data->service_url = context.service_url; @@ -252,6 +256,7 @@ void plugin_get_metadata(void *state, grpc_auth_metadata_context context, uv_mutex_unlock(&p_state->plugin_mutex); uv_async_send(&p_state->plugin_async); + return 0; // Async processing. } void plugin_uv_close_cb(uv_handle_t *handle) { diff --git a/packages/grpc-native-core/ext/call_credentials.h b/packages/grpc-native-core/ext/call_credentials.h index adcff845..323eb4f2 100644 --- a/packages/grpc-native-core/ext/call_credentials.h +++ b/packages/grpc-native-core/ext/call_credentials.h @@ -75,9 +75,13 @@ typedef struct plugin_state { uv_async_t plugin_async; } plugin_state; -void plugin_get_metadata(void *state, grpc_auth_metadata_context context, - grpc_credentials_plugin_metadata_cb cb, - void *user_data); +int plugin_get_metadata( + void *state, grpc_auth_metadata_context context, + grpc_credentials_plugin_metadata_cb cb, + void *user_data, + grpc_metadata creds_md[GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX], + size_t *num_creds_md, grpc_status_code *status, + const char **error_details); void plugin_destroy_state(void *state); From ae5219310ee12b17469cefa4fdee3caf4c57e98d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 6 Oct 2017 19:50:50 +0200 Subject: [PATCH 13/20] Align with js-core package --- packages/grpc-native-core/index.d.ts | 123 ++++++++++++++++++--------- 1 file changed, 85 insertions(+), 38 deletions(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index f2c014d2..4f30f8ae 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -1,5 +1,7 @@ declare module "grpc" { + /// import { Message, Service } from "protobufjs"; + import { SecureContext } from "tls"; /** * Load a ProtoBuf.js object as a gRPC object. @@ -282,6 +284,8 @@ declare module "grpc" { */ request: any; + private constructor(); + /** * Get the endpoint this call/stream is connected to. * @return The URI of the endpoint @@ -315,6 +319,8 @@ declare module "grpc" { */ metadata: Metadata; + private constructor(); + /** * Get the endpoint this call/stream is connected to. * @return The URI of the endpoint @@ -353,6 +359,8 @@ declare module "grpc" { */ request: any; + private constructor(); + /** * Get the endpoint this call/stream is connected to. * @return The URI of the endpoint @@ -376,6 +384,8 @@ declare module "grpc" { * with duplex streaming. */ export class ServerDuplexStream { + private constructor(); + /** * Get the endpoint this call/stream is connected to. * @return The URI of the endpoint @@ -409,62 +419,57 @@ declare module "grpc" { */ type sendUnaryData = (error: ServiceError | null, value: any, trailer?: Metadata, flags?: number) => void; + /** + * A class for storing metadata. Keys are normalized to lowercase ASCII. + */ export class Metadata { /** - * Class for storing metadata. Keys are normalized to lowercase ASCII. - * ``` - * var metadata = new metadata_module.Metadata(); - * metadata.set('key1', 'value1'); - * metadata.add('key1', 'value2'); - * metadata.get('key1') // returns ['value1', 'value2'] - * ``` - */ - constructor(); - - /** - * Sets the given value for the given key, replacing any other values associated - * with that key. Normalizes the key. - * @param key The key to set + * 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' + * if the normalized key ends with '-bin'. */ - set(key: string, value: string | Buffer): void; + set(key: string, value: MetadataValue): void; /** - * Adds the given value for the given key. Normalizes the key. - * @param key The key to add to. + * 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' + * if the normalized key ends with '-bin'. */ - add(key: string, value: string | Buffer): void; + add(key: string, value: MetadataValue): void; /** - * Remove the given key and any associated values. Normalizes the key. - * @param key The key to remove + * 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 to get - * @return The values associated with that key + * @param key The key whose value should be retrieved. + * @return A list of values associated with the given key. */ - get(key: string): Array; + get(key: string): MetadataValue[]; /** - * Get a map of each key to a single associated value. This reflects the most - * common way that people will want to see metadata. - * @return A key/value mapping of the metadata + * 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(): { [index: string]: string | Buffer }; + getMap(): { [key: string]: MetadataValue }; /** - * Clone the metadata object. - * @return {Metadata} The new cloned object + * 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. @@ -492,15 +497,15 @@ declare module "grpc" { * `details` in `StatusObject`, and `code` and `metadata` are the * same as in that object. */ - export class ServiceError extends Error { + export interface ServiceError extends Error { /** * The error code, a key of {@link grpc.status} that is not `grpc.status.OK` */ - code: status; + code?: status; /** * Trailing metadata sent with the status, if applicable */ - metadata: Metadata; + metadata?: Metadata; } /** @@ -828,13 +833,47 @@ declare module "grpc" { * This cannot be constructed directly. Instead, instances of this class should * be created using the factory functions in `grpc.credentials` */ - export class ChannelCredentials {} + 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 class CallCredentials {} + export interface CallCredentials { + /** + * Asynchronously generates a new Metadata object. + * @param options Options used in generating the Metadata object. + */ + generateMetadata(options: object): Promise; + + /** + * 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; + } /** * Google credential from https://github.com/google/google-auth-library-nodejs lib. @@ -887,7 +926,7 @@ declare module "grpc" { * 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 {Object} options Options to apply to channel creation + * @param options Options to apply to channel creation */ constructor(address: string, credentials: ChannelCredentials, options?: object) @@ -1050,6 +1089,8 @@ declare module "grpc" { * 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. @@ -1068,6 +1109,8 @@ declare module "grpc" { * from the server side. */ export class ClientReadableStream { + private constructor(); + /** * Cancel the ongoing call. Results in the call ending with a CANCELLED status, * unless it has already ended with some other status. @@ -1086,6 +1129,8 @@ declare module "grpc" { * the client side. */ export class ClientWritableStream { + 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. @@ -1115,6 +1160,8 @@ declare module "grpc" { * duplex streaming. */ export class ClientDuplexStream { + 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. @@ -1144,7 +1191,7 @@ declare module "grpc" { * @param error The error, if the call failed * @param value The response value, if the call succeeded */ - export type requestCallback = (error: Error | null, value: any) => void; + export type requestCallback = (error: ServiceError | null, value: any) => void; /** * Return the underlying channel object for the specified client From 4647cc125bf73d6f814d2cabc3c0d4c8c232380d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 6 Oct 2017 20:00:08 +0200 Subject: [PATCH 14/20] Use the correct Google credentials interface --- packages/grpc-native-core/index.d.ts | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index 4f30f8ae..34fa7be7 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -798,7 +798,7 @@ declare module "grpc" { * @param googleCredential The Google credential object to use * @return The resulting credentials object */ - createFromGoogleCredential(googleCredential: GoogleCredential): CallCredentials; + createFromGoogleCredential(googleCredential: GoogleOAuth2Client): CallCredentials; /** * Combine a ChannelCredentials with any number of CallCredentials into a single @@ -876,14 +876,12 @@ declare module "grpc" { } /** - * Google credential from https://github.com/google/google-auth-library-nodejs lib. - * The object definition is copied from `ts/lib/auth/credentials.ts` + * 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 GoogleCredential { - refresh_token?: string; - expiry_date?: number; - access_token?: string; - token_type?: string; + export interface GoogleOAuth2Client { + getRequestMetadata(optUri: string, metadataCallback: (err: Error, headers: any) => void) } /** From 56690ca16b44b80976404af940312c6514e5f198 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 6 Oct 2017 20:19:20 +0200 Subject: [PATCH 15/20] Add Node typings dependency --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index 05647b47..2e9798ba 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ }, "license": "Apache-2.0", "devDependencies": { + "@types/node": "^8.0.32", "del": "^3.0.0", "execa": "^0.8.0", "gulp": "^3.9.1", From 836f9bdb36c36251ad777438de043dc6de932919 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 6 Oct 2017 20:20:16 +0200 Subject: [PATCH 16/20] Make streams extend Readable, Writeable and Duplex types from Node.js stream pkg --- packages/grpc-native-core/index.d.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index 34fa7be7..77a4a198 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -1,7 +1,7 @@ declare module "grpc" { - /// import { Message, Service } from "protobufjs"; import { SecureContext } from "tls"; + import { Duplex, Readable, Writable } from "stream"; /** * Load a ProtoBuf.js object as a gRPC object. @@ -308,7 +308,7 @@ declare module "grpc" { * A stream that the server can read from. Used for calls that are streaming * from the client side. */ - export class ServerReadableStream { + export class ServerReadableStream extends Readable { /** * Indicates if the call has been cancelled */ @@ -343,7 +343,7 @@ declare module "grpc" { * A stream that the server can write to. Used for calls that are streaming * from the server side. */ - export class ServerWriteableStream { + export class ServerWriteableStream extends Writable { /** * Indicates if the call has been cancelled */ @@ -383,7 +383,7 @@ declare module "grpc" { * A stream that the server can read from or write to. Used for calls * with duplex streaming. */ - export class ServerDuplexStream { + export class ServerDuplexStream extends Duplex { private constructor(); /** @@ -1106,7 +1106,7 @@ declare module "grpc" { * A stream that the client can read from. Used for calls that are streaming * from the server side. */ - export class ClientReadableStream { + export class ClientReadableStream extends Readable { private constructor(); /** From 11307ac0a6f4e7aa33fd5ee4923720bcf99f4991 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 6 Oct 2017 20:25:33 +0200 Subject: [PATCH 17/20] Missed a return type on the OAuth2 client interface --- packages/grpc-native-core/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index 77a4a198..78434396 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -881,7 +881,7 @@ declare module "grpc" { * The definition is copied from `ts/lib/auth/oauth2client.ts` */ export interface GoogleOAuth2Client { - getRequestMetadata(optUri: string, metadataCallback: (err: Error, headers: any) => void) + getRequestMetadata(optUri: string, metadataCallback: (err: Error, headers: any) => void): void; } /** From a026502019068f482dad37d1adb0d7fd4028cef9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 6 Oct 2017 20:25:43 +0200 Subject: [PATCH 18/20] Order imports correctly --- packages/grpc-native-core/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index 78434396..37c6f1ca 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -1,7 +1,7 @@ declare module "grpc" { import { Message, Service } from "protobufjs"; - import { SecureContext } from "tls"; import { Duplex, Readable, Writable } from "stream"; + import { SecureContext } from "tls"; /** * Load a ProtoBuf.js object as a gRPC object. From 00b4bc6e598f4ea846041b5e154f2b421bdb23aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn?= Date: Fri, 6 Oct 2017 21:48:16 +0200 Subject: [PATCH 19/20] Added missing streaming implementations --- packages/grpc-native-core/index.d.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/grpc-native-core/index.d.ts b/packages/grpc-native-core/index.d.ts index 37c6f1ca..f3a091eb 100644 --- a/packages/grpc-native-core/index.d.ts +++ b/packages/grpc-native-core/index.d.ts @@ -1126,7 +1126,7 @@ declare module "grpc" { * A stream that the client can write to. Used for calls that are streaming from * the client side. */ - export class ClientWritableStream { + export class ClientWritableStream extends Writable { private constructor(); /** @@ -1138,7 +1138,7 @@ declare module "grpc" { * @param callback Callback for when this chunk of data is flushed * @return As defined for [Writable]{@link external:Writable} */ - write(message: any, flags: writeFlags, callback: Function): boolean; + write(message: any, flags?: any&writeFlags, callback?: Function): boolean; /** * Cancel the ongoing call. Results in the call ending with a CANCELLED status, @@ -1157,7 +1157,7 @@ declare module "grpc" { * A stream that the client can read from or write to. Used for calls with * duplex streaming. */ - export class ClientDuplexStream { + export class ClientDuplexStream extends Duplex { private constructor(); /** @@ -1169,7 +1169,7 @@ declare module "grpc" { * @param callback Callback for when this chunk of data is flushed * @return As defined for [Writable]{@link external:Writable} */ - write(message: any, flags: writeFlags, callback: Function): boolean; + write(message: any, flags?: any&writeFlags, callback?: Function): boolean; /** * Cancel the ongoing call. Results in the call ending with a CANCELLED status, From cb82bc7b127f072c35a5e9e95c9c20a9d6de08c8 Mon Sep 17 00:00:00 2001 From: murgatroid99 Date: Tue, 10 Oct 2017 14:10:21 -0700 Subject: [PATCH 20/20] Upgrade npm versions for every version of node in test scripts --- run-tests.bat | 1 + run-tests.sh | 1 + 2 files changed, 2 insertions(+) diff --git a/run-tests.bat b/run-tests.bat index 207efed2..92c2b299 100644 --- a/run-tests.bat +++ b/run-tests.bat @@ -31,6 +31,7 @@ call npm install || goto :error for %%v in (4.8.4 6.11.3 7.9.0 8.5.0) do ( nvm install %%v nvm use %%v + npm install -g npm node -e "console.log(process.versions)" call .\node_modules\.bin\gulp clean.all || goto :error diff --git a/run-tests.sh b/run-tests.sh index c1a76889..4e276ff4 100755 --- a/run-tests.sh +++ b/run-tests.sh @@ -48,6 +48,7 @@ do echo "Switching to node version $version" nvm install $version nvm use $version + npm install -g npm set -ex mkdir -p "reports/node$version"