feat: TypeScript microgenerator - initial pull request

feat: TypeScript microgenerator

.circleci/config.yml

@@ -8,12 +8,13 @@ jobs:
       - run:
           name: Install protoc
           command: |
-            apt-get update
-            apt-get install protobuf-compiler
+            sudo apt-get update
+            sudo apt-get install protobuf-compiler
       - run:
           name: Run tests
           command: |
-            true
+            npm install
+            npm test
 workflows:
   version: 2
   tests:

.gitignore

@@ -0,0 +1,17 @@
+**/*.log
+**/node_modules
+.coverage
+.nyc_output
+coverage/
+docs/
+out/
+test.js
+config.yaml
+ignored
+build
+.vscode
+package-lock.json
+pbjs-genfiles/
+.DS_Store
+.idea
+.baseline-test-out

package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@google-cloud/gapic-generator",
+  "version": "0.0.1",
+  "description": "Google API Client Library Generator for TypeScript, written in TypeScript.",
+  "engines": {
+    "node": ">=8.13.0"
+  },
+  "files": [
+    "build/src",
+    "pbjs-genfiles"
+  ],
+  "bin": {
+    "protoc-gen-typescript_gapic": "build/src/cli.js"
+  },
+  "scripts": {
+    "test": "c8 --reporter=lcov mocha build/test",
+    "codecov": "c8 --reporter=lcov mocha build/test && c8 report",
+    "lint": "gts check",
+    "clean": "gts clean",
+    "compile-protos": "pbjs -p protos -t static-module -o pbjs-genfiles/plugin.js google/protobuf/compiler/plugin.proto google/api/annotations.proto google/api/client.proto google/longrunning/operations.proto && pbts pbjs-genfiles/plugin.js -o pbjs-genfiles/plugin.d.ts",
+    "compile": "tsc -p . && cp -r typescript/test/protos build/test/",
+    "fix": "gts fix",
+    "prepare": "npm run compile-protos && npm run compile",
+    "pretest": "npm run compile-protos && npm run compile"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/googleapis/gapic-generator-typescript.git"
+  },
+  "author": "Google LLC",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/googleapis/gapic-generator-typescript/issues"
+  },
+  "homepage": "https://github.com/googleapis/gapic-generator-typescript#readme",
+  "devDependencies": {
+    "@types/command-line-args": "^5.0.0",
+    "@types/get-stdin": "^5.0.1",
+    "@types/google-protobuf": "^3.2.7",
+    "@types/mocha": "^5.2.5",
+    "@types/node": "^11.12.0",
+    "@types/nunjucks": "^3.1.0",
+    "@types/rimraf": "^2.0.2",
+    "assert-rejects": "^1.0.0",
+    "c8": "^5.0.1",
+    "codecov": "^3.0.4",
+    "espower-typescript": "^9.0.0",
+    "google-gax": "^1.3.0",
+    "gts": "^0.9.0",
+    "intelli-espower-loader": "^1.0.1",
+    "mocha": "^5.2.0",
+    "power-assert": "^1.6.0",
+    "rimraf": "^3.0.0",
+    "typescript": "~3.5.3"
+  },
+  "dependencies": {
+    "command-line-args": "^5.0.2",
+    "get-stdin": "^6.0.0",
+    "google-protobuf": "^3.6.1",
+    "nunjucks": "^3.1.3",
+    "protobufjs": "^6.8.8"
+  }
+}

pbjs-genfiles/README.md

@@ -0,0 +1,5 @@
+This folder will contain JavaScript files and TypeScript type definitions
+generated by `pbjs` and `pbts` tools (from `protobufjs`) based on the protobuf
+definitions from the `protos` folder.
+
+Use `npm run compile-protos` to generate these files.

protos/google/api/README.md

@@ -0,0 +1,46 @@
+## API Protos
+
+This folder contains the schema of the configuration model for Google's
+internal API serving platform, which handles routing, quotas, monitoring,
+logging, and the like.
+
+Google refers to this configuration colloquially as the "service config",
+and the `service.proto` file in this directory is the entry point for
+understanding these.
+
+## Using these protos
+
+To be honest, we probably open sourced way too much of this (basically by
+accident). There are a couple files in here you are most likely to be
+interested in: `http.proto`, `documentation.proto`, `auth.proto`, `annotations.proto`,
+`field_behavior.proto` and `resource.proto`.
+
+### HTTP and REST
+
+The `http.proto` file contains the `Http` message (which then is wrapped
+in an annotation in `annotations.proto`), which provides a specification
+for REST endpoints and verbs (`GET`, `POST`, etc.) on RPC methods.
+We recommend use of this annotation for describing the relationship
+between RPCs and REST endpoints.
+
+### Documentation
+
+The `documentation.proto` file contains a `Documentation` message which
+provides a mechanism to fully describe an API, allowing a tool to build
+structured documentation artifacts.
+
+### Authentication
+
+The `auth.proto` file contains descriptions of both authentication rules
+and authenticaion providers, allowing you to describe what your services
+expect and accept from clients.
+
+## api-compiler
+
+Google provides a tool called [api-compiler][], which is a tool that accepts
+a protocol buffer descriptor and a YAML file specifying some of the
+options described in `service.proto`, and outputs a much more thorough
+`Service` descriptor based on the information it infers from the protos
+themselves.
+
+  [api-compiler]: https://github.com/googleapis/api-compiler

protos/google/api/annotations.proto

@@ -0,0 +1,33 @@
+// Copyright (c) 2015, Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.api;
+
+import "google/api/http.proto";
+import "google/protobuf/descriptor.proto";
+
+option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";
+option java_multiple_files = true;
+option java_outer_classname = "AnnotationsProto";
+option java_package = "com.google.api";
+option objc_class_prefix = "GAPI";
+
+
+extend google.protobuf.MethodOptions {
+  // The HTTP bindings for this method.
+  // See `google/api/http.proto`.
+  HttpRule http = 72295728;
+}

protos/google/api/auth.proto

@@ -0,0 +1,179 @@
+// Copyright 2018 Google LLC.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.api;
+
+option go_package = "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig";
+option java_multiple_files = true;
+option java_outer_classname = "AuthProto";
+option java_package = "com.google.api";
+option objc_class_prefix = "GAPI";
+
+
+// `Authentication` defines the authentication configuration for an API.
+//
+// Example for an API targeted for external use:
+//
+//     name: calendar.googleapis.com
+//     authentication:
+//       providers:
+//       - id: google_calendar_auth
+//         jwks_uri: https://www.googleapis.com/oauth2/v1/certs
+//         issuer: https://securetoken.google.com
+//       rules:
+//       - selector: "*"
+//         requirements:
+//           provider_id: google_calendar_auth
+message Authentication {
+  // A list of authentication rules that apply to individual API methods.
+  //
+  // **NOTE:** All service configuration rules follow "last one wins" order.
+  repeated AuthenticationRule rules = 3;
+
+  // Defines a set of authentication providers that a service supports.
+  repeated AuthProvider providers = 4;
+}
+
+// Authentication rules for the service.
+//
+// By default, if a method has any authentication requirements, every request
+// must include a valid credential matching one of the requirements.
+// It's an error to include more than one kind of credential in a single
+// request.
+//
+// If a method doesn't have any auth requirements, request credentials will be
+// ignored.
+message AuthenticationRule {
+  // Selects the methods to which this rule applies.
+  //
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
+  string selector = 1;
+
+  // The requirements for OAuth credentials.
+  OAuthRequirements oauth = 2;
+
+  // If true, the service accepts API keys without any other credential.
+  bool allow_without_credential = 5;
+
+  // Requirements for additional authentication providers.
+  repeated AuthRequirement requirements = 7;
+}
+
+// Configuration for an anthentication provider, including support for
+// [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).
+message AuthProvider {
+  // The unique identifier of the auth provider. It will be referred to by
+  // `AuthRequirement.provider_id`.
+  //
+  // Example: "bookstore_auth".
+  string id = 1;
+
+  // Identifies the principal that issued the JWT. See
+  // https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1
+  // Usually a URL or an email address.
+  //
+  // Example: https://securetoken.google.com
+  // Example: 1234567-compute@developer.gserviceaccount.com
+  string issuer = 2;
+
+  // URL of the provider's public key set to validate signature of the JWT. See
+  // [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
+  // Optional if the key set document:
+  //  - can be retrieved from
+  //    [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html
+  //    of the issuer.
+  //  - can be inferred from the email domain of the issuer (e.g. a Google service account).
+  //
+  // Example: https://www.googleapis.com/oauth2/v1/certs
+  string jwks_uri = 3;
+
+  // The list of JWT
+  // [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).
+  // that are allowed to access. A JWT containing any of these audiences will
+  // be accepted. When this setting is absent, only JWTs with audience
+  // "https://[Service_name][google.api.Service.name]/[API_name][google.protobuf.Api.name]"
+  // will be accepted. For example, if no audiences are in the setting,
+  // LibraryService API will only accept JWTs with the following audience
+  // "https://library-example.googleapis.com/google.example.library.v1.LibraryService".
+  //
+  // Example:
+  //
+  //     audiences: bookstore_android.apps.googleusercontent.com,
+  //                bookstore_web.apps.googleusercontent.com
+  string audiences = 4;
+
+  // Redirect URL if JWT token is required but no present or is expired.
+  // Implement authorizationUrl of securityDefinitions in OpenAPI spec.
+  string authorization_url = 5;
+}
+
+// OAuth scopes are a way to define data and permissions on data. For example,
+// there are scopes defined for "Read-only access to Google Calendar" and
+// "Access to Cloud Platform". Users can consent to a scope for an application,
+// giving it permission to access that data on their behalf.
+//
+// OAuth scope specifications should be fairly coarse grained; a user will need
+// to see and understand the text description of what your scope means.
+//
+// In most cases: use one or at most two OAuth scopes for an entire family of
+// products. If your product has multiple APIs, you should probably be sharing
+// the OAuth scope across all of those APIs.
+//
+// When you need finer grained OAuth consent screens: talk with your product
+// management about how developers will use them in practice.
+//
+// Please note that even though each of the canonical scopes is enough for a
+// request to be accepted and passed to the backend, a request can still fail
+// due to the backend requiring additional scopes or permissions.
+message OAuthRequirements {
+  // The list of publicly documented OAuth scopes that are allowed access. An
+  // OAuth token containing any of these scopes will be accepted.
+  //
+  // Example:
+  //
+  //      canonical_scopes: https://www.googleapis.com/auth/calendar,
+  //                        https://www.googleapis.com/auth/calendar.read
+  string canonical_scopes = 1;
+}
+
+// User-defined authentication requirements, including support for
+// [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).
+message AuthRequirement {
+  // [id][google.api.AuthProvider.id] from authentication provider.
+  //
+  // Example:
+  //
+  //     provider_id: bookstore_auth
+  string provider_id = 1;
+
+  // NOTE: This will be deprecated soon, once AuthProvider.audiences is
+  // implemented and accepted in all the runtime components.
+  //
+  // The list of JWT
+  // [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).
+  // that are allowed to access. A JWT containing any of these audiences will
+  // be accepted. When this setting is absent, only JWTs with audience
+  // "https://[Service_name][google.api.Service.name]/[API_name][google.protobuf.Api.name]"
+  // will be accepted. For example, if no audiences are in the setting,
+  // LibraryService API will only accept JWTs with the following audience
+  // "https://library-example.googleapis.com/google.example.library.v1.LibraryService".
+  //
+  // Example:
+  //
+  //     audiences: bookstore_android.apps.googleusercontent.com,
+  //                bookstore_web.apps.googleusercontent.com
+  string audiences = 2;
+}