protoc-gen-grpc-gateway-ts is a Typescript client generator for the grpc-gateway project. It generates idiomatic Typescript clients that connect the web frontend and golang backend fronted by grpc-gateway.

Overview

protoc-gen-grpc-gateway-ts

protoc-gen-grpc-gateway-ts is a Typescript client generator for the grpc-gateway project. It generates idiomatic Typescript clients that connect the web frontend and golang backend fronted by grpc-gateway.

Features:

  1. idiomatic Typescript clients and messages
  2. Supports both One way and server side streaming gRPC calls
  3. POJO request construction guarded by message type definitions, which is way easier compare to grpc-web
  4. No need to use swagger/open api to generate client code for the web.

Get Started

Install protoc-gen-grpc-gateway-ts

You will need to install protoc-gen-grpc-gateway-ts before it could be picked up by the protoc command. Just run cd protoc-gen-grpc-gateway-ts; go install .

Sample Usage

protoc-gen-grpc-gateway-ts will be used along with the protoc command. A sample invocation looks like the following:

protoc --grpc-gateway-ts_out=ts_import_roots=$(pwd),ts_import_root_aliases=base:. input.proto

As a result the generated file will be input.pb.ts in the same directory.

Parameters:

ts_import_roots

Since a protoc plugin do not get the import path information as what's specified in protoc -I, this parameter gives the plugin the same information to figure out where a specific type is coming from so that it can generate import statement at the top of the generated typescript file. Defaults to $(pwd)

ts_import_root_aliases

If a project has setup alias for their import. This parameter can be used to keep up with the project setup. It will print out alias instead of relative path in the import statement. Default is "".

ts_import_roots & ts_import_root_aliases are useful when you have setup import alias in your project with the project asset bundler, e.g. Webpack.

fetch_module_directory and fetch_module_filename

protoc-gen-grpc-gateway-ts will a shared typescript file with communication functions. These two parameters together will determine where the fetch module file is located. Default to $(pwd)/fetch.pb.ts

use_proto_names

To keep the same convention with grpc-gateway v2 & protojson. The field name in message generated by this library is in lowerCamelCase by default. If you prefer to make it stick the same with what is defined in the proto file, this option needs to be set to true.

logtostderr

Turn Ton logging to stderr. Default to false.

loglevel

Defines the logging levels. Default to info. Valid values are: debug, info, warn, error

Examples:

The following shows how to use the generated typescript code.

Proto file: counter.proto

// file: counter.proto
message Request {
  int32 counter = 1;
}

message Response {
  int32 result = 1;
}

service CounterService {
  rpc Increase(Request) returns (Response);
  rpc Increase10X(Request) returns (stream Response);
}

Run the following command to generate the Typescript client:

protoc --grpc-gateway-ts_out=. counter.proto

Then a counter.pb.ts file will be available at the current directory. You can use it like the following example.

import {CounterService} from './counter.pb'

// increase the given number once  
async function increase(base: number): Promise<number> {
  const resp = await CounterService.Increase({counter: base})
  return resp.result
} 

// increase the base repeatedly and return all results returned back from server
// the notifier after the request will be called once a result comes back from server streaming
async function increaseRepeatedly(base: number): Promise<number[]> {
  let results = []
  await CounterService.Increase10X({base}, (resp: Response) => {
    result.push(resp.result)
  })

  return results
}

##License

Copyright 2020 Square, 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.
Issues
  • Properly encode Uint8Array fields

    Properly encode Uint8Array fields

    Fixes: https://github.com/grpc-ecosystem/protoc-gen-grpc-gateway-ts/issues/22

    Binary data should be represented as base64 encoded string in the JSON encoded body. Use replacer to return base64 encoded string when Uint8Array type is detected.

    Signed-off-by: Artem Chernyshev [email protected]

    opened by Unix4ever 10
  • Handle rendering of URL Query Parameters in renderURL

    Handle rendering of URL Query Parameters in renderURL

    The following is extracted from this file: http.proto

    // HTTP | gRPC
    // -----|-----
    // `GET /v1/messages/123456`  | `GetMessage(name: "messages/123456")`
    //
    // Any fields in the request message which are not bound by the path template
    // automatically become HTTP query parameters if there is no HTTP request body.
    // For example:
    //
    //     service Messaging {
    //       rpc GetMessage(GetMessageRequest) returns (Message) {
    //         option (google.api.http) = {
    //             get:"/v1/messages/{message_id}"
    //         };
    //       }
    //     }
    //     message GetMessageRequest {
    //       message SubMessage {
    //         string subfield = 1;
    //       }
    //       string message_id = 1; // Mapped to URL path.
    //       int64 revision = 2;    // Mapped to URL query parameter `revision`.
    //       SubMessage sub = 3;    // Mapped to URL query parameter `sub.subfield`.
    //     }
    //
    // This enables a HTTP JSON to RPC mapping as below:
    //
    // HTTP | gRPC
    // -----|-----
    // `GET /v1/messages/123456?revision=2&sub.subfield=foo` |
    // `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:
    // "foo"))`
    //
    

    However it seems like renderURL function in protoc-gen-grpc-gateway doesn't render the fields in the request message which are not bound by the path template to become URL query parameters if there is no HTTP request body.

    Any advice on how to handle this would be great! Thanks in advance 🙏🏼

    opened by atreya2011 8
  • Is there anyway to pass custom headers ?

    Is there anyway to pass custom headers ?

    It is useful to pass a header like Authorization to the query, I can't find a way to pass it

    opened by didierfranc 8
  • Handling well-known types

    Handling well-known types

    Given the following proto message:

    syntax = "proto3";
    
    import "google/protobuf/timestamp.proto";
    import "google/protobuf/any.proto";
    
    message User {
      string                    id       = 1;
      string                    name     = 2;
      google.protobuf.Timestamp my_field = 3;
    }
    
    // https://developers.google.com/protocol-buffers/docs/proto3#any
    message ErrorStatus {
      string   message                     = 1;
      repeated google.protobuf.Any details = 2;
    }
    

    The following TypeScript is being generated which throws a type error because neither timestamp.pb.ts nor any.pb exist.

    /*
    * This file is a generated Typescript file for GRPC Gateway, DO NOT MODIFY
    */
    
    import * as GoogleProtobufAny from "../google/protobuf/any.pb"
    import * as GoogleProtobufTimestamp from "../google/protobuf/timestamp.pb"
    
    export type User = {
      id?: string
      name?: string
      myField?: GoogleProtobufTimestamp.Timestamp
    }
    
    export type ErrorStatus = {
      message?: string
      details?: GoogleProtobufAny.Any[]
    }
    

    Please let me know if I am missing any steps in the generation process 🙏🏼 I used the following command to generate the above TypeScript file.

    protoc -I. --grpc-gateway-ts_out=. --grpc-gateway-ts_opt logtostderr=true --grpc-gateway-ts_opt loglevel=debug ./proto/example.proto

    opened by atreya2011 7
  • Handling errors

    Handling errors

    The fetch function seems to ignore the .ok status of the fetch response. This means that if there is a gRPC error, data is returned of the error type instead of the declared response type.

    Shouldn’t the fetch function throw in case of http errors (I.e. if .ok is false), so the client can catch errors? (And so there is no typing inconsistency)

    opened by remko 7
  • Use === in generated code

    Use === in generated code

    Using === is recommended in modern JavaScript / TypeScript since it also verifies for typing without any implicit conversions

    opened by abatilo 7
  • Use `import type` for type imports in template

    Use `import type` for type imports in template

    When a proto file has imports, the generator generates code like

    import * as GoogleProtobufTimestamp from "./google/protobuf/timestamp.pb";
    

    The default setup of TypeScript in the bundler I use is strict, and is set up to give errors on type-only imports:

    error TS1371: This import is never used as a value and must use 'import type' because 'importsNotUsedAsValues' is set to 'error'.
    

    I can work around this by loosening the tsconfig setting.

    Would it be possible to replace the imports generated for these kinds of import by import type to avoid these TypeScript errors on strict setups?

    opened by remko 6
  • Handle rendering of URL Query Parameters in renderURL

    Handle rendering of URL Query Parameters in renderURL

    Resolves #9

    TODO:

    • [x] Create a TypeScript function in template to build URL query parameters
    • [x] Handle nested message types.
    • [x] Handle primitive repeated fields.
    opened by atreya2011 6
  • Bumped protobuf version to v1.26

    Bumped protobuf version to v1.26

    Bumped google.golang.org/protobuf and its dependency github.com/golang/protobuf to current latest stable versions.

    opened by vgarvardt 5
  • Add support for HTTP PATCH method

    Add support for HTTP PATCH method

    I have created a separate PR for adding support for HTTP PATCH method. 🙇🏼

    opened by atreya2011 5
  • Support of required fields

    Support of required fields

    protoc-gen-grpc-gateway-ts always put ? suffix for the fields, as fields in proto3 are basically optional. But I want the generator to support omitting the ? suffix when it's marked as non-optional in a way.

    An idea is to consider a field is a required and If the field is specified as google.api.field_behavior = REQUIRED annotation (cf. https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto#L61 and an example https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto#L154).

    opened by junm-cloudnatix 0
  • Inconsistent Well-Known Types handling with grpc-gateway

    Inconsistent Well-Known Types handling with grpc-gateway

    Previously discussed in https://github.com/grpc-ecosystem/protoc-gen-grpc-gateway-ts/issues/4

    Although we should run most other protoc plugins with WKT definitions come with the protoc (timestamp.pb, duration.pb etc.). In the case of protoc-gen-grpc-gateway-ts, we should generate TypeScript definitions compatible with grpc-gateway's JSON mapping (and protoc-gen-openapiv2).

    Currently, by running the protoc-gen-grpc-gateway-ts on timestamp.pb, we will get the underlying definition of the timestamp.

    // example message
    export type Message = {
      value?: string
      waitPeriod?: GoogleProtobufDuration.Duration
      ts?: GoogleProtobufTimestamp.Timestamp
    }
    // the definition of GoogleProtobufTimestamp.Timestamp
    export type Timestamp = {
      seconds?: string
      nanos?: number
    }
    

    Which will be rejected by grpc-gateway. The correct JSON mapping of the timestamp is a datetime in RFC3339(nano) format, which can be fulfilled by the default behavior of JSON.stringify a Date object in JavaScript.

    I think we still need to set up exception rules for parsing those WKTs, at least for Timestamp and Duration.

    https://github.com/atreya2011/protoc-gen-grpc-gateway-ts/commit/a1e3d5c3381788a3f673174b4c3d17b0476bc0e3 seems to be a good patch without the handling of wrappers, duration and etc.

    opened by lixin9311 8
  • Add optional fields support

    Add optional fields support

    As of protobuf 3.15 optional fields are available, but they are not supported by the generator:

    test/optional/v1/has_optional_field.proto: is a proto3 file that contains optional fields, but code generator protoc-gen-grpc-gateway-ts hasn't been updated to support optional fields in proto3. Please ask the owner of this code generator to support proto3 optional.--grpc-gateway-ts_out:
    

    test/optional/v1/has_optional_field.proto contents:

    syntax = "proto3";
    
    package test.optional.v1;
    
    message HasOptionalField {
      string not_optional = 1;
      optional string not_required = 2;
    }
    
    opened by vgarvardt 5
Releases(v1.1.1)
Owner
gRPC Ecosystem
gRPC Ecosystem that complements gRPC
gRPC Ecosystem
V3IO Frames ("Frames") is a Golang based remote data frames access (over gRPC or HTTP stream)

V3IO Frames ("Frames") is a multi-model open-source data-access library that provides a unified high-performance DataFrame API for working with different types of data sources (backends). The library was developed by Iguazio to simplify working with data in the Iguazio Data Science Platform ("the platform"), but it can be extended to support additional backend types.

null 23 Aug 5, 2021
protoc-gen-grpc-gateway-ts is a Typescript client generator for the grpc-gateway project. It generates idiomatic Typescript clients that connect the web frontend and golang backend fronted by grpc-gateway.

protoc-gen-grpc-gateway-ts protoc-gen-grpc-gateway-ts is a Typescript client generator for the grpc-gateway project. It generates idiomatic Typescript

gRPC Ecosystem 34 Sep 12, 2021
A Protocol Buffers compiler that generates optimized marshaling & unmarshaling Go code for ProtoBuf APIv2

vtprotobuf, the Vitess Protocol Buffers compiler This repository provides the protoc-gen-go-vtproto plug-in for protoc, which is used by Vitess to gen

PlanetScale 320 Sep 19, 2021
Simple Web based configuration generator for WireGuard. Demo:

Wg Gen Web Simple Web based configuration generator for WireGuard. Why another one ? All WireGuard UI implementations are trying to manage the service

vx3r 641 Sep 22, 2021
Modern network boot server.

bofied demo.mp4 Modern network boot server. Overview bofied is a network boot server. It provides everything you need to PXE boot a node, from a (prox

Felix Pojtinger 77 Sep 20, 2021
webrpc is a schema-driven approach to writing backend services for modern Web apps and networks

webrpc is a schema-driven approach to writing backend servers for the Web. Write your server's api interface in a schema format of RIDL or JSON, and t

null 389 Sep 14, 2021
A simple RPC framework with protobuf service definitions

Twirp is a framework for service-to-service communication emphasizing simplicity and minimalism. It generates routing and serialization from API defin

Twitch 5.1k Sep 20, 2021
Một script nho nhỏ viết bằng Go để crawl toàn bộ điểm thi THPTQG-2021

Crawl toàn bộ điểm thi THPTQG-2021 Một script nho nhỏ viết bằng Go để crawl toàn bộ điểm thi THPTQG-2021, mình đã crawl sẵn toàn bộ ở đây: https://dri

null 16 Sep 13, 2021
Erda's infrastructure framework

Erda Infra Translations: English | 简体中文 Erda Infra is a lightweight microservices framework implements by golang, which offers many useful modules and

Erda 75 Sep 22, 2021
Generate types and service clients from protobuf definitions annotated with http rules.

protoc-gen-typescript-http Generates Typescript types and service clients from protobuf definitions annotated with http rules. The generated types fol

Einride 14 Aug 6, 2021
Use Consul to do service discovery, use gRPC +kafka to do message produce and consume. Use redis to store result.

目录 gRPC/consul/kafka简介 gRPC+kafka的Demo gRPC+kafka整体示意图 限流器 基于redis计数器生成唯一ID kafka生产消费 kafka生产消费示意图 本文kafka生产消费过程 基于pprof的性能分析Demo 使用pprof统计CPU/HEAP数据的

null 38 Jan 31, 2021
A protoc-gen-go wrapper including an RPC stub generator

// Copyright 2013 Google. All rights reserved. // // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE fi

Kyle Lemons 35 May 13, 2020
Golang gRPC Middlewares: interceptor chaining, auth, logging, retries and more.

Golang gRPC Middlewares: interceptor chaining, auth, logging, retries and more.

gRPC Ecosystem 4k Sep 24, 2021
Create a gRPC Server from Database

xo-grpc Create a gRPC Server from the generated code by the xo project. Requirements Go 1.16 or superior protoc xo, protoc-gen-go and protoc-gen-go-gr

Walter Wanderley 19 Sep 8, 2021
A new way of working with Protocol Buffers.

Buf All documentation is hosted at https://buf.build. Please head over there for more details. Goal Buf’s long-term goal is to enable schema-driven de

null 2.8k Sep 26, 2021
Create a gRPC server from code generated by sqlc

sqlc-grpc Create a gRPC Server from the generated code by the awesome sqlc project. Dependencies Go 1.16 or superior protoc sqlc, protoc-gen-go and pr

Walter Wanderley 41 Sep 15, 2021
A suite of gRPC debugging tools. Like Fiddler/Charles but for gRPC.

grpc-tools A suite of tools for gRPC debugging and development. Like Fiddler/Charles but for gRPC! The main tool is grpc-dump which transparently inte

Bradley Kemp 967 Sep 24, 2021
The Go language implementation of gRPC. HTTP/2 based RPC

gRPC-Go The Go implementation of gRPC: A high performance, open source, general RPC framework that puts mobile and HTTP/2 first. For more information

grpc 14.5k Sep 23, 2021