[Proposal] Consider use grpc-gateway way to implement the CLI, UI and API-Server interactions

[JaredTan95]

Is your feature request related to a problem? Please describe.

Now the starship back-end apiserver uses the gin framework to implement the http server and expose the interface to the UI and CLI, but this is very fragile, if you do not pay attention to changing the UI and CLI when changing the apiserver's API, it can easily cause the UI and CLi to not work. And we also have the api documentation issue like

Describe the solution you'd like I've learned some good ways in the community that maybe we can learn from.

In general, we need to move from manually exposing HTTP APIs to using grpc-gateway, so our first step is to change from gin to grpc communication.

1. define grpc protocol , maybe follows https://github.com/tricorder-observability/starship/issues/125
2. using grpc-gateway as grpc proxy and add an entrypoint for the HTTP reverse-proxy server:
   • add an entrypoint for the HTTP reverse-proxy server:

     
     package main

import ( "context" "flag" "net/http"

"github.com/golang/glog" "github.com/grpc-ecosystem/grpc-gateway/v2/runtime" "google.golang.org/grpc" "google.golang.org/grpc/credentials/insecure"

gw "github.com/yourorg/yourrepo/proto/gen/go/your/service/v1/your_service" // Update )

var ( // command-line options: // gRPC server endpoint grpcServerEndpoint = flag.String("grpc-server-endpoint", "localhost:9090", "gRPC server endpoint") )

func run() error { ctx := context.Background() ctx, cancel := context.WithCancel(ctx) defer cancel()

// Register gRPC server endpoint // Note: Make sure the gRPC server is running properly and accessible mux := runtime.NewServeMux() opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())} err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux, *grpcServerEndpoint, opts) if err != nil { return err }

// Start HTTP server (and proxy calls to gRPC server endpoint) return http.ListenAndServe(":8081", mux) }

func main() { flag.Parse() defer glog.Flush()

if err := run(); err != nil { glog.Fatal(err) } }

4.  Generate OpenAPI definitions using `protoc-gen-openapiv2` as API swagger docs
5.  Generate `typescript` SDK with defined grpc-proto

[nascentcore-eng]

@jmzwcn @owl-ltt Do you 2 have some ideas regarding this? I know you already expressed similar sentiment. But I am not entirely convinced of the required work.

[jmzwcn]

Yes, I support to use gRPC-web. Keep architecture efficient and simply.

gRPC-web is very direct and easy-to-use.

https://github.com/emart-io/cross/blob/main/zwan/service/attendant.proto https://github.com/emart-io/cross/tree/main/zwan/service/js https://github.com/emart-io/cross/blob/main/pwa/nginx.conf#L14 https://github.com/emart-io/cross/blob/main/pwa/src/api.service.ts

[jmzwcn]

https://github.com/grpc/grpc-web

[feuyeux]

Providing a series api to web UI or admin UI, api first is the best choice, for example, swagger - as same as grpc behavior, defining a proto at firt and then generating the skeleton codes. Instead of code first, it's a friendly way to communicate between the frontend and backend.

And about the protocol, http is better than grpc, since grpc-web is not a mature way for product. For me, grpc is better to use between the machines.

[JaredTan95]

Yes, My original proposal was not to use grpc-web, just use grpc-gateway as an entry point to the api, which is implemented by grpc and protocol. mgmt-UI still use the RESTful style request to grpc-gateway. FYI @yaxiong-zhao

BTW, grpc-web has some network requirements for browsers and backends.

[nascentcore-eng]

grpc-web has some network requirements for browsers and backends.

What are these requirements? Could you provide links to the detailed doc? @JaredTan95