Adapt latest protocol changes (#258)

* Squashed 'sdk-core/src/main/service-protocol/' changes from 4378d559..29b28f98

29b28f98 Modify Input/Output schema in deployment_manifest_schema.json (#80)
26d91e69 Replace protocol Empty message with custom one, so we remove the dependency on protobuf built-in messages (#79)
61ae44b2 Update documentation on error codes (#77)
576a1b26 Add HandlerType. Fix #1092 (#76)
0624d092 Payload schema for input and output. This provides basic format awareness. (#74)

git-subtree-dir: sdk-core/src/main/service-protocol
git-subtree-split: 29b28f9867734bc01dd47c4666d9d56c90b626f5

* Changes due to the protocol update

Author: slinkydeveloper

sdk-core/src/main/java/dev/restate/sdk/core/DeploymentManifest.java

@@ -39,12 +39,7 @@ public DeploymentManifest(
                                 .withComponentType(convertComponentType(svc.getComponentType()))
                                 .withHandlers(
                                     svc.getHandlers().stream()
-                                        .map(
-                                            method ->
-                                                new Handler()
-                                                    .withName(method.getName())
-                                                    .withInputSchema(method.getInputSchema())
-                                                    .withOutputSchema(method.getOutputSchema()))
+                                        .map(method -> new Handler().withName(method.getName()))
                                         .collect(Collectors.toList())))
                     .collect(Collectors.toList()));
   }

sdk-core/src/main/java/dev/restate/sdk/core/Entries.java

@@ -9,7 +9,6 @@
 package dev.restate.sdk.core;
 
 import com.google.protobuf.ByteString;
-import com.google.protobuf.Empty;
 import com.google.protobuf.InvalidProtocolBufferException;
 import com.google.protobuf.MessageLite;
 import dev.restate.generated.service.protocol.Protocol;

sdk-core/src/main/service-protocol/deployment_manifest_schema.json

@@ -41,19 +41,95 @@
                   "type": "string",
                   "pattern": "^([a-zA-Z]|_[a-zA-Z0-9])[a-zA-Z0-9_]*$"
                 },
-                "inputSchema": {},
-                "outputSchema": {}
+                "handlerType": {
+                  "title": "HandlerType",
+                  "enum": ["EXCLUSIVE", "SHARED"],
+                  "description": "If unspecified, defaults to EXCLUSIVE for Virtual Object. This should be unset for Services."
+                },
+                "input": {
+                  "type": "object",
+                  "title": "InputPayload",
+                  "description": "Description of an input payload. This will be used by Restate to validate incoming requests.",
+                  "properties": {
+                    "required": {
+                      "type": "boolean",
+                      "description": "If true, a body MUST be sent with a content-type, even if the body length is zero."
+                    },
+                    "contentType": {
+                      "type": "string",
+                      "description": "Content type of the input. It can accept wildcards, in the same format as the 'Accept' header. When this field is unset, it implies emptiness, meaning no content-type/body is expected."
+                    },
+                    "jsonSchema": {}
+                  },
+                  "additionalProperties": false,
+                  "default": {
+                    "contentType": "*/*",
+                    "required": false
+                  },
+                  "examples": {
+                    "empty input": {},
+                    "non empty json input": {
+                      "required": true,
+                      "contentType": "application/json",
+                      "jsonSchema": true
+                    },
+                    "either empty or non empty json input": {
+                      "required": false,
+                      "contentType": "application/json",
+                      "jsonSchema": true
+                    },
+                    "bytes input": {
+                      "required": true,
+                      "contentType": "application/octet-stream"
+                    }
+                  }
+                },
+                "output": {
+                  "type": "object",
+                  "title": "OutputPayload",
+                  "description": "Description of an output payload.",
+                  "properties": {
+                    "contentType": {
+                      "type": "string",
+                      "description": "Content type set on output. This will be used by Restate to set the output content type at the ingress."
+                    },
+                    "setContentTypeIfEmpty": {
+                      "type": "boolean",
+                      "description": "If true, the specified content-type is set even if the output is empty."
+                    },
+                    "jsonSchema": {}
+                  },
+                  "additionalProperties": false,
+                  "default": {
+                    "contentType": "application/json",
+                    "setContentTypeIfEmpty": false
+                  },
+                  "examples": {
+                    "empty output": {
+                      "setContentTypeIfEmpty": false
+                    },
+                    "non-empty json output": {
+                      "contentType": "application/json",
+                      "setContentTypeIfEmpty": false,
+                      "jsonSchema": true
+                    },
+                    "protobuf output": {
+                      "contentType": "application/proto",
+                      "setContentTypeIfEmpty": true
+                    }
+                  }
+                }
               },
-              "required": [ "name" ],
+              "required": ["name"],
               "additionalProperties": false
             }
           }
         },
-        "required": [ "fullyQualifiedComponentName","componentType", "handlers" ],
+        "required": ["fullyQualifiedComponentName", "componentType", "handlers"],
         "additionalProperties": false
       }
     }
   },
-  "required": [ "minProtocolVersion", "maxProtocolVersion", "components" ],
+  "required": ["minProtocolVersion", "maxProtocolVersion", "components"],
   "additionalProperties": false
-}
+}

sdk-core/src/main/service-protocol/dev/restate/service/protocol.proto

@@ -11,8 +11,6 @@ syntax = "proto3";
 
 package dev.restate.service.protocol;
 
-import "google/protobuf/empty.proto";
-
 option java_package = "dev.restate.generated.service.protocol";
 option go_package = "restate.dev/sdk-go/pb/service/protocol";
 
@@ -49,7 +47,7 @@ message CompletionMessage {
   uint32 entry_index = 1;
 
   oneof result {
-    google.protobuf.Empty empty = 13;
+    Empty empty = 13;
     bytes value = 14;
     Failure failure = 15;
   };
@@ -68,12 +66,10 @@ message SuspensionMessage {
 
 // Type: 0x0000 + 3
 message ErrorMessage {
-  // The code can be:
-  // * Any of the error codes defined by OutputStreamEntry.failure (see Failure message)
-  // * JOURNAL_MISMATCH = 32, that is when the SDK cannot replay a journal due to the mismatch between the journal and the actual code.
-  // * PROTOCOL_VIOLATION = 33, that is when the SDK receives an unexpected message or an expected message variant, given its state.
-  //
-  // If 16 < code < 32, or code > 33, the runtime will interpret it as code 2 (UNKNOWN).
+  // The code can be any HTTP status code, as described https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml.
+  // In addition, we define the following error codes that MAY be used by the SDK for better error reporting:
+  // * JOURNAL_MISMATCH = 570, that is when the SDK cannot replay a journal due to the mismatch between the journal and the actual code.
+  // * PROTOCOL_VIOLATION = 571, that is when the SDK receives an unexpected message or an expected message variant, given its state.
   uint32 code = 1;
   // Contains a concise error message, e.g. Throwable#getMessage() in Java.
   string message = 2;
@@ -132,7 +128,7 @@ message GetStateEntryMessage {
   bytes key = 1;
 
   oneof result {
-    google.protobuf.Empty empty = 13;
+    Empty empty = 13;
     bytes value = 14;
     Failure failure = 15;
   };
@@ -184,7 +180,7 @@ message SleepEntryMessage {
   uint64 wake_up_time = 1;
 
   oneof result {
-    google.protobuf.Empty empty = 13;
+    Empty empty = 13;
     Failure failure = 15;
   }
 }
@@ -259,10 +255,7 @@ message CompleteAwakeableEntryMessage {
 // This failure object carries user visible errors,
 // e.g. invocation failure return value or failure result of an InvokeEntryMessage.
 message Failure {
-  // The code should be any of the gRPC error codes,
-  // as defined here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc
-  //
-  // If code > 16, the runtime will interpret it as code 2 (UNKNOWN).
+  // The code can be any HTTP status code, as described https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml.
   uint32 code = 1;
   // Contains a concise error message, e.g. Throwable#getMessage() in Java.
   string message = 2;
@@ -272,3 +265,6 @@ message Header {
   string key = 1;
   string value = 2;
 }
+
+message Empty {
+}

sdk-core/src/test/java/dev/restate/sdk/core/DeferredTestSuite.java

@@ -14,7 +14,6 @@
 import static org.assertj.core.api.InstanceOfAssertFactories.list;
 import static org.assertj.core.api.InstanceOfAssertFactories.type;
 
-import com.google.protobuf.Empty;
 import dev.restate.generated.sdk.java.Java;
 import dev.restate.generated.service.protocol.Protocol;
 import java.util.function.Supplier;
@@ -370,7 +369,7 @@ public Stream<TestDefinition> definitions() {
                     ProtoUtils.inputMessage(),
                     Protocol.CompletionMessage.newBuilder()
                         .setEntryIndex(2)
-                        .setEmpty(Empty.getDefaultInstance()))
+                        .setEmpty(Protocol.Empty.getDefaultInstance()))
                 .onlyUnbuffered()
                 .assertingOutput(
                     messages -> {

sdk-core/src/test/java/dev/restate/sdk/core/ProtoUtils.java

@@ -9,7 +9,6 @@
 package dev.restate.sdk.core;
 
 import com.google.protobuf.ByteString;
-import com.google.protobuf.Empty;
 import com.google.protobuf.MessageLite;
 import com.google.protobuf.MessageLiteOrBuilder;
 import dev.restate.generated.sdk.java.Java;
@@ -160,7 +159,7 @@ public static Protocol.GetStateEntryMessage.Builder getStateMessage(String key,
   public static Protocol.GetStateEntryMessage getStateEmptyMessage(String key) {
     return Protocol.GetStateEntryMessage.newBuilder()
         .setKey(ByteString.copyFromUtf8(key))
-        .setEmpty(Empty.getDefaultInstance())
+        .setEmpty(Protocol.Empty.getDefaultInstance())
         .build();
   }
 

sdk-core/src/test/java/dev/restate/sdk/core/SleepTestSuite.java

@@ -14,7 +14,6 @@
 import static org.assertj.core.api.InstanceOfAssertFactories.LONG;
 import static org.assertj.core.api.InstanceOfAssertFactories.type;
 
-import com.google.protobuf.Empty;
 import com.google.protobuf.MessageLiteOrBuilder;
 import dev.restate.generated.service.protocol.Protocol;
 import dev.restate.sdk.common.TerminalException;
@@ -55,7 +54,7 @@ public Stream<TestDefinitions.TestDefinition> definitions() {
                 inputMessage("Till"),
                 Protocol.SleepEntryMessage.newBuilder()
                     .setWakeUpTime(Instant.now().toEpochMilli())
-                    .setEmpty(Empty.getDefaultInstance())
+                    .setEmpty(Protocol.Empty.getDefaultInstance())
                     .build())
             .expectingOutput(outputMessage("Hello"), END_MESSAGE)
             .named("Sleep 1000 ms sleep completed"),
@@ -78,7 +77,7 @@ public Stream<TestDefinitions.TestDefinition> definitions() {
                                     (i % 3 == 0)
                                         ? Protocol.SleepEntryMessage.newBuilder()
                                             .setWakeUpTime(Instant.now().toEpochMilli())
-                                            .setEmpty(Empty.getDefaultInstance())
+                                            .setEmpty(Protocol.Empty.getDefaultInstance())
                                             .build()
                                         : Protocol.SleepEntryMessage.newBuilder()
                                             .setWakeUpTime(Instant.now().toEpochMilli())

sdk-core/src/test/java/dev/restate/sdk/core/StateTestSuite.java

@@ -12,7 +12,6 @@
 import static dev.restate.sdk.core.ProtoUtils.*;
 import static org.assertj.core.api.Assertions.assertThat;
 
-import com.google.protobuf.Empty;
 import dev.restate.generated.service.protocol.Protocol;
 import dev.restate.sdk.common.TerminalException;
 import dev.restate.sdk.core.TestDefinitions.TestInvocationBuilder;
@@ -37,7 +36,7 @@ public Stream<TestDefinitions.TestDefinition> definitions() {
             .withInput(
                 startMessage(2),
                 inputMessage("Till"),
-                getStateMessage("STATE").setEmpty(Empty.getDefaultInstance()))
+                getStateMessage("STATE").setEmpty(Protocol.Empty.getDefaultInstance()))
             .expectingOutput(outputMessage("Hello Unknown"), END_MESSAGE)
             .named("With GetStateEntry already completed empty"),
         this.getState()

sdk-http-vertx/src/test/kotlin/dev/restate/sdk/http/vertx/RestateHttpEndpointTest.kt

@@ -10,7 +10,6 @@ package dev.restate.sdk.http.vertx
 
 import com.fasterxml.jackson.databind.ObjectMapper
 import com.google.protobuf.ByteString
-import com.google.protobuf.Empty
 import com.google.protobuf.MessageLite
 import dev.restate.generated.service.protocol.Protocol.*
 import dev.restate.sdk.common.CoreSerdes