diff --git a/gulpfile.js b/gulpfile.js index 396918b6..dbb0af11 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -32,11 +32,11 @@ 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', 'js.install', 'native.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', 'js.install', 'native.install']); gulp.task('lint', 'Emit linting errors in source and test files', @@ -82,4 +82,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 4caf864b..2e9798ba 100644 --- a/package.json +++ b/package.json @@ -8,29 +8,24 @@ "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": { + "@types/node": "^8.0.32", "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/.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/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); diff --git a/packages/grpc-native-core/gulpfile.js b/packages/grpc-native-core/gulpfile.js index 35a265ac..8a714ee6 100644 --- a/packages/grpc-native-core/gulpfile.js +++ b/packages/grpc-native-core/gulpfile.js @@ -21,6 +21,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'); @@ -73,3 +74,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/index.d.ts b/packages/grpc-native-core/index.d.ts new file mode 100644 index 00000000..f3a091eb --- /dev/null +++ b/packages/grpc-native-core/index.d.ts @@ -0,0 +1,1221 @@ +declare module "grpc" { + import { Message, Service } from "protobufjs"; + import { Duplex, Readable, Writable } from "stream"; + import { SecureContext } from "tls"; + + /** + * Load a ProtoBuf.js object as a gRPC object. + * @param value The ProtoBuf.js reflection object to load + * @param options Options to apply to the loaded file + * @return The resulting gRPC object. + */ + export function loadObject(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 { + [name: string]: GrpcObject | typeof Client | Message; + } + + /** + * 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: logVerbosity): void; + + /** + * Server object that stores request handlers and delegates incoming requests to those handlers + */ + export class Server { + /** + * Constructs a server object that stores request handlers and delegates + * incoming requests to those handlers + * @param options Options that should be passed to the internal server + * implementation + * ``` + * var server = new grpc.Server(); + * server.addProtoService(protobuf_service_descriptor, service_implementation); + * server.bind('address:port', server_credential); + * server.start(); + * ``` + */ + constructor(options?: object); + + /** + * Start the server and begin handling requests + */ + start(): void; + + /** + * Registers a handler to handle the named method. Fails if there already is + * a handler for the given method. Returns true on success + * @param name The name of the method that the provided function should + * handle/respond to. + * @param handler Function that takes a stream of + * request values and returns a stream of response values + * @param serialize Serialization function for responses + * @param deserialize Deserialization function for requests + * @param type The streaming type of method that this handles + * @return True if the handler was set. False if a handler was already + * set for that name. + */ + register(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 | ServiceDefinition, 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. + * @return The bound port number or 0 if the opreation failed. + */ + bind(port: string, creds: ServerCredentials): number; + } + + /** + * 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; + + /** + * An EventEmitter. Used for unary calls. + */ + 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; + + private constructor(); + + /** + * Get the endpoint this call/stream is connected to. + * @return The URI of the endpoint + */ + getPeer(): string; + + /** + * Send the initial metadata for a writable stream. + * @param responseMetadata Metadata to send + */ + sendMetadata(responseMetadata: Metadata): void; + } + + /** + * User provided method to handle client streaming methods on the server. + */ + type handleClientStreamingCall = (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 extends Readable { + /** + * Indicates if the call has been cancelled + */ + cancelled: boolean; + + /** + * The request metadata from the client + */ + metadata: Metadata; + + private constructor(); + + /** + * Get the endpoint this call/stream is connected to. + * @return The URI of the endpoint + */ + getPeer(): string; + + /** + * Send the initial metadata for a writable stream. + * @param responseMetadata Metadata to send + */ + sendMetadata(responseMetadata: Metadata): void; + } + + /** + * User provided method to handle server streaming methods on the server. + */ + type handleServerStreamingCall = (call: ServerWriteableStream) => void; + + /** + * A stream that the server can write to. Used for calls that are streaming + * from the server side. + */ + export class ServerWriteableStream extends Writable { + /** + * Indicates if the call has been cancelled + */ + cancelled: boolean; + + /** + * The request metadata from the client + */ + metadata: Metadata; + + /** + * The request message from the client + */ + request: any; + + private constructor(); + + /** + * Get the endpoint this call/stream is connected to. + * @return The URI of the endpoint + */ + getPeer(): string; + + /** + * Send the initial metadata for a writable stream. + * @param responseMetadata Metadata to send + */ + sendMetadata(responseMetadata: Metadata): void; + } + + /** + * User provided method to handle bidirectional streaming calls on the server. + */ + type handleBidiStreamingCall = (call: ServerDuplexStream) => void; + + /** + * A stream that the server can read from or write to. Used for calls + * with duplex streaming. + */ + export class ServerDuplexStream extends Duplex { + private constructor(); + + /** + * Get the endpoint this call/stream is connected to. + * @return The URI of the endpoint + */ + getPeer(): string; + + /** + * Send the initial metadata for a writable stream. + * @param responseMetadata Metadata to send + */ + sendMetadata(responseMetadata: Metadata): void; + } + + /** + * A deserialization function + * @param data The byte sequence to deserialize + * @return The data deserialized as a value + */ + type deserialize = (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; + + /** + * A class for storing metadata. Keys are normalized to lowercase ASCII. + */ + export class Metadata { + /** + * Sets the given value for the given key by replacing any other values + * associated with that key. Normalizes the key. + * @param key The key to whose value should be set. + * @param value The value to set. Must be a buffer if and only + * if the normalized key ends with '-bin'. + */ + set(key: string, value: MetadataValue): void; + + /** + * Adds the given value for the given key by appending to a list of previous + * values associated with that key. Normalizes the key. + * @param key The key for which a new value should be appended. + * @param value The value to add. Must be a buffer if and only + * if the normalized key ends with '-bin'. + */ + add(key: string, value: MetadataValue): void; + + /** + * Removes the given key and any associated values. Normalizes the key. + * @param key The key whose values should be removed. + */ + remove(key: string): void; + + /** + * Gets a list of all values associated with the key. Normalizes the key. + * @param key The key whose value should be retrieved. + * @return A list of values associated with the given key. + */ + get(key: string): MetadataValue[]; + + /** + * Gets a plain object mapping each key to the first value associated with it. + * This reflects the most common way that people will want to see metadata. + * @return A key/value mapping of the metadata. + */ + getMap(): { [key: string]: MetadataValue }; + + /** + * Clones the metadata object. + * @return The newly cloned object. + */ + clone(): Metadata; + } + + export type MetadataValue = string | Buffer; + + /** + * Represents the status of a completed request. If `code` is + * `grpc.status.OK`, then the request has completed successfully. + * Otherwise, the request has failed, `details` will contain a description of + * the error. Either way, `metadata` contains the trailing response metadata + * sent by the server when it finishes processing the call. + */ + export interface StatusObject { + /** + * The error code, a key of `grpc.status` + */ + code: status; + /** + * Human-readable description of the status + */ + details: string; + /** + * Trailing metadata sent with the status, if applicable + */ + metadata: Metadata; + } + + /** + * Describes how a request has failed. The member `message` will be the same as + * `details` in `StatusObject`, and `code` and `metadata` are the + * same as in that object. + */ + export interface ServiceError extends Error { + /** + * The error code, a key of {@link grpc.status} that is not `grpc.status.OK` + */ + code?: status; + /** + * Trailing metadata sent with the status, if applicable + */ + metadata?: Metadata; + } + + /** + * ServerCredentials factories + */ + export class ServerCredentials { + /** + * Create insecure server credentials + * @return The ServerCredentials + */ + static createInsecure(): ServerCredentials; + /** + * Create SSL server credentials + * @param rootCerts Root CA certificates for validating client certificates + * @param keyCertPairs A list of private key and certificate chain pairs to + * be used for authenticating the server + * @param checkClientCertificate Indicates that the server should request + * and verify the client's certificates. + * Defaults to `false`. + * @return The ServerCredentials + */ + static 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: GoogleOAuth2Client): CallCredentials; + + /** + * Combine a ChannelCredentials with any number of CallCredentials into a single + * ChannelCredentials object. + * @param channelCredential The ChannelCredentials to start with + * @param credentials The CallCredentials to compose + * @return A credentials object that combines all of the input credentials + */ + combineChannelCredentials(channelCredential: ChannelCredentials, ...credentials: CallCredentials[]): ChannelCredentials; + + /** + * Combine any number of CallCredentials into a single CallCredentials object + * @param credentials The CallCredentials to compose + * @return A credentials object that combines all of the input credentials + */ + combineCallCredentials(...credentials: CallCredentials[]): CallCredentials; + + /** + * Create an insecure credentials object. This is used to create a channel that + * does not use SSL. This cannot be composed with anything. + * @return The insecure credentials object + */ + createInsecure(): ChannelCredentials; + }; + + /** + * Metadata generator function. + */ + export type metadataGenerator = (params: { service_url: string }, callback: (error: Error | null, metadata?: Metadata) => void) => void; + + /** + * This cannot be constructed directly. Instead, instances of this class should + * be created using the factory functions in `grpc.credentials` + */ + export interface ChannelCredentials { + /** + * Returns a copy of this object with the included set of per-call credentials + * expanded to include callCredentials. + * @param callCredentials A CallCredentials object to associate with this + * instance. + */ + compose(callCredentials: CallCredentials): ChannelCredentials; + + /** + * Gets the set of per-call credentials associated with this instance. + */ + getCallCredentials(): CallCredentials; + + /** + * Gets a SecureContext object generated from input parameters if this + * instance was created with createSsl, or null if this instance was created + * with createInsecure. + */ + getSecureContext(): SecureContext | null; + } + + /** + * This cannot be constructed directly. Instead, instances of this class should + * be created using the factory functions in `grpc.credentials` + */ + export interface CallCredentials { + /** + * Asynchronously generates a new Metadata object. + * @param options Options used in generating the Metadata object. + */ + generateMetadata(options: object): Promise; + + /** + * Creates a new CallCredentials object from properties of both this and + * another CallCredentials object. This object's metadata generator will be + * called first. + * @param callCredentials The other CallCredentials object. + */ + compose(callCredentials: CallCredentials): CallCredentials; + } + + /** + * This is the required interface from the OAuth2Client object + * from https://github.com/google/google-auth-library-nodejs lib. + * The definition is copied from `ts/lib/auth/oauth2client.ts` + */ + export interface GoogleOAuth2Client { + getRequestMetadata(optUri: string, metadataCallback: (err: Error, headers: any) => void): void; + } + + /** + * Creates a constructor for a client with the given methods, as specified in + * the methods argument. The resulting class will have an instance method for + * each method in the service, which is a partial application of one of the + * `grpc.Client` request methods, depending on `requestSerialize` + * and `responseSerialize`, with the `method`, `serialize`, and `deserialize` + * arguments predefined. + * @param methods An object mapping method names to method attributes + * @param serviceName The fully qualified name of the service + * @param classOptions An options object. + * @return New client constructor, which is a subclass of `grpc.Client`, and + * has the same arguments as that constructor. + */ + export function makeGenericClientConstructor( + methods: ServiceDefinition, + serviceName: string, + classOptions: GenericClientOptions, + ): typeof Client; + + /** + * Options for generic client constructor. + */ + export interface GenericClientOptions { + /** + * Indicates that the old argument order should be used for methods, with + * optional arguments at the end instead of the callback at the end. This + * option is only a temporary stopgap measure to smooth an API breakage. + * It is deprecated, and new code should not use it. + */ + deprecatedArgumentOrder?: boolean; + } + + /** + * Create a client with the given methods + */ + export class Client { + /** + * A generic gRPC client. Primarily useful as a base class for generated clients + * @param address Server address to connect to + * @param credentials Credentials to use to connect to the server + * @param options Options to apply to channel creation + */ + constructor(address: string, credentials: ChannelCredentials, options?: object) + + /** + * Make a unary request to the given method, using the given serialize + * and deserialize functions, with the given argument. + * @param method The name of the method to request + * @param serialize The serialization function for inputs + * @param deserialize The deserialization function for outputs + * @param argument The argument to the call. Should be serializable with + * serialize + * @param metadata Metadata to add to the call + * @param options Options map + * @param callback The callback to for when the response is received + * @return An event emitter for stream related events + */ + makeUnaryRequest( + 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; + + /** + * An EventEmitter. Used for unary calls. + */ + export class ClientUnaryCall { + private constructor(); + + /** + * Cancel the ongoing call. Results in the call ending with a CANCELLED status, + * unless it has already ended with some other status. + */ + cancel(): void; + + /** + * Get the endpoint this call/stream is connected to. + * @return The URI of the endpoint + */ + getPeer(): string; + } + + /** + * A stream that the client can read from. Used for calls that are streaming + * from the server side. + */ + export class ClientReadableStream extends Readable { + private constructor(); + + /** + * Cancel the ongoing call. Results in the call ending with a CANCELLED status, + * unless it has already ended with some other status. + */ + cancel(): void; + + /** + * Get the endpoint this call/stream is connected to. + * @return The URI of the endpoint + */ + getPeer(): string; + } + + /** + * A stream that the client can write to. Used for calls that are streaming from + * the client side. + */ + export class ClientWritableStream extends Writable { + private constructor(); + + /** + * Write a message to the request stream. If serializing the argument fails, + * the call will be cancelled and the stream will end with an error. + * @param message The message to write. Must be a valid argument to the + * serialize function of the corresponding method + * @param flags Flags to modify how the message is written + * @param callback Callback for when this chunk of data is flushed + * @return As defined for [Writable]{@link external:Writable} + */ + write(message: any, flags?: any&writeFlags, callback?: Function): boolean; + + /** + * Cancel the ongoing call. Results in the call ending with a CANCELLED status, + * unless it has already ended with some other status. + */ + cancel(): void; + + /** + * Get the endpoint this call/stream is connected to. + * @return The URI of the endpoint + */ + getPeer(): string; + } + + /** + * A stream that the client can read from or write to. Used for calls with + * duplex streaming. + */ + export class ClientDuplexStream extends Duplex { + private constructor(); + + /** + * Write a message to the request stream. If serializing the argument fails, + * the call will be cancelled and the stream will end with an error. + * @param message The message to write. Must be a valid argument to the + * serialize function of the corresponding method + * @param flags Flags to modify how the message is written + * @param callback Callback for when this chunk of data is flushed + * @return As defined for [Writable]{@link external:Writable} + */ + write(message: any, flags?: any&writeFlags, callback?: Function): boolean; + + /** + * Cancel the ongoing call. Results in the call ending with a CANCELLED status, + * unless it has already ended with some other status. + */ + cancel(): void; + + /** + * Get the endpoint this call/stream is connected to. + * @return The URI of the endpoint + */ + getPeer(): string; + } + + /** + * Client request callback + * @param error The error, if the call failed + * @param value The response value, if the call succeeded + */ + export type requestCallback = (error: ServiceError | 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/index.js b/packages/grpc-native-core/index.js index 0d814cc3..af597f70 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) { @@ -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/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 64a73a04..4a0c220d 100644 --- a/packages/grpc-native-core/package.json +++ b/packages/grpc-native-core/package.json @@ -19,11 +19,8 @@ "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", "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", - "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" }, @@ -38,12 +35,9 @@ "protobufjs": "^5.0.0" }, "devDependencies": { - "async": "^2.0.1", "electron-mocha": "^3.1.1", - "google-auth-library": "^0.9.2", "google-protobuf": "^3.0.0", - "istanbul": "^0.4.4", - "jsdoc": "^3.3.2" + "istanbul": "^0.4.4" }, "engines": { "node": ">=4" @@ -58,18 +52,18 @@ "files": [ "LICENSE", "README.md", - "deps/grpc/src/proto", - "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", - "deps/grpc/third_party/zlib", - "deps/grpc/third_party/boringssl", + "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/src/client.js b/packages/grpc-native-core/src/client.js index d3c39ca4..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 + * @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/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. */ 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 */ diff --git a/packages/grpc-native-core/templates/package.json.template b/packages/grpc-native-core/templates/package.json.template index fe9290a8..47efb460 100644 --- a/packages/grpc-native-core/templates/package.json.template +++ b/packages/grpc-native-core/templates/package.json.template @@ -21,11 +21,8 @@ "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", "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", - "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" }, @@ -40,12 +37,9 @@ "protobufjs": "^5.0.0" }, "devDependencies": { - "async": "^2.0.1", "electron-mocha": "^3.1.1", - "google-auth-library": "^0.9.2", "google-protobuf": "^3.0.0", - "istanbul": "^0.4.4", - "jsdoc": "^3.3.2" + "istanbul": "^0.4.4" }, "engines": { "node": ">=4" @@ -60,18 +54,18 @@ "files": [ "LICENSE", "README.md", - "deps/grpc/src/proto", - "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", - "deps/grpc/third_party/zlib", - "deps/grpc/third_party/boringssl", + "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/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" diff --git a/test/gulpfile.js b/test/gulpfile.js index 8dcab40d..469f8d23 100644 --- a/test/gulpfile.js +++ b/test/gulpfile.js @@ -32,6 +32,10 @@ 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'], {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" + } +}