From 77ec8a66d72ab154e7b5febee20ab53a942eba75 Mon Sep 17 00:00:00 2001 From: Francesco Guardiani Date: Fri, 23 Jun 2023 09:13:55 +0200 Subject: [PATCH 1/3] Add ingress documentation (#36) * Add ingress documentation * Apply suggestions from code review Co-authored-by: Giselle van Dongen * A bit of clarification about the built-in service --------- Co-authored-by: Giselle van Dongen --- docs/ingress.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/ingress.md diff --git a/docs/ingress.md b/docs/ingress.md new file mode 100644 index 00000000..6e596473 --- /dev/null +++ b/docs/ingress.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 7 +--- + +# Invoking services + +There are different ways to invoke a Restate service: + +* From within another service, as described in the [SDK service communication documentation](./typescript-sdk/service-communication.md) +* By sending a request to any Restate runtime using either [Connect (gRPC on HTTP)](https://connect.build/docs/protocol/), gRPC or gRPC-web + +## Connect (gRPC on HTTP) + +Restate supports the [Connect Protocol](https://connect.build/docs/protocol/), allowing you to send gRPC-like requests as regular HTTP requests. + +It supports encoding request/response bodies as either JSON or Protobuf, it works on HTTP 1.1 or more, allows you to send requests directly from the browser, and it doesn't require to generate a client. + +For example, to invoke the service `org.example.Greeter` method `Greet` using `curl`: + +```shell +curl -X POST http:///org.example.Greeter/Greet -H 'content-type: application/json' -d '{"name": "Pete"}' +``` + +You should see the response: + +```json +{"greeting":"Hello Pete"} +``` + +The rules to invoke a service are the following: + +* The request path is in the format of `{serviceName}/{methodName}` +* The request method is `POST` +* The request body is encoded either with: + * Json, with the header `Content-Type: application/json`, or with + * Protobuf, with the header `Content-Type: application/proto` + +The response body will have the same content type as the request. + +For more details on the Connect protocol, check out the [Connect documentation](https://connect.build/). + +## gRPC and gRPC-web + +Restate is fully compatible with the [gRPC](https://grpc.io/), meaning you can send requests to your services as regular gRPC requests. + +You can use any gRPC code generator to generate a gRPC client to invoke a Restate service. Check out the [awesome-grpc page](https://github.com/grpc-ecosystem/awesome-grpc) for a comprehensive list of clients, code generators and tools. + +For example, to invoke the service `org.example.Greeter` method `Greet` using [`grpcurl`](https://github.com/fullstorydev/grpcurl): + +```shell +grpcurl -plaintext -d '{"name": "Pete"} org.example.Greeter/Greet +``` + +Restate supports [gRPC reflections](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md), hence some tools like `grpcurl` will automatically discover the protobuf definitions of the services to invoke. + +For example, to query the available services in the runtime: + +```shell +grpcurl -plaintext describe +``` + +Restate also natively supports gRPC-web. You can use a [gRPC-web code generator](https://www.npmjs.com/package/grpc-web) and point it directly to Restate, without using a 3rd party proxy to translate gRPC-web to gRPC. + +## Invoke a service without waiting for the response + +You can invoke a service without waiting for the response, similar to [one-way calls in the SDK](./typescript-sdk/service-communication.md), by using the Restate built-in `dev.restate.Ingress/Invoke` service method, which can be invoked like any other user service, using gRPC, gRPC-web or Connect. + +For example, using [Connect](#connect-grpc-on-http) and `curl`: + +```shell +curl -X POST http:///dev.restate.Ingress/Invoke -H 'content-type: application/json' -d '{"service": "org.example.Greeter", "method": "Greet", "payload": {"name": "Pete"}}' +``` + +The response contains the [service invocation identifier](./deployment-operations/manage-invocations.md#service-invocation-identifier). You can use this identifier to manage the invocation as described in ["Manage invocations" documention](deployment-operations/manage-invocations.md). + +For a complete documentation of the `dev.restate.Ingress` built-in service, check out the [Restate protobuf definitions](https://github.com/restatedev/proto/blob/main/dev/restate/services.proto). + +:::tip +This feature can be especially useful when you need to invoke a service method implementing a long-running workflow. +::: From e303e16d22c470f26f914e3036697fa999b93b66 Mon Sep 17 00:00:00 2001 From: Till Rohrmann Date: Fri, 23 Jun 2023 15:39:17 +0200 Subject: [PATCH 2/3] Bump Restate runtime version to 0.1.4 --- docusaurus.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 07d827e8..4a2e31e9 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -57,7 +57,7 @@ const config = { variableInjector, // replaces eg VAR::RESTATE_DIST_VERSION with config strings { replacements: { - RESTATE_DIST_VERSION: '0.1.3', + RESTATE_DIST_VERSION: '0.1.4', TYPESCRIPT_SDK_VERSION: '1.0.27', TOUR_VERSION: 'v0.0.1' }, From a141b635f8dcc71f16ed6f55da6843a610892118 Mon Sep 17 00:00:00 2001 From: Till Rohrmann Date: Tue, 27 Jun 2023 11:55:44 +0200 Subject: [PATCH 3/3] Bump Restate runtime version to 0.1.5 --- docusaurus.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 4a2e31e9..53e65513 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -57,7 +57,7 @@ const config = { variableInjector, // replaces eg VAR::RESTATE_DIST_VERSION with config strings { replacements: { - RESTATE_DIST_VERSION: '0.1.4', + RESTATE_DIST_VERSION: '0.1.5', TYPESCRIPT_SDK_VERSION: '1.0.27', TOUR_VERSION: 'v0.0.1' },