Merge pull request #272 from twitchtv/release_v7

Set v7 protocol as current version in docs

Author: marioizquierdo

PROTOCOL.md

@@ -1,7 +1,7 @@
 # Twirp Wire Protocol
 
 This document defines the Twirp wire protocol over HTTP. The
-current protocol version is v5.
+current protocol version is v7.
 
 ## Overview
 
@@ -25,7 +25,9 @@ proto messages, and works with any HTTP client and any HTTP version.
 In [ABNF syntax](https://tools.ietf.org/html/rfc5234), Twirp's URLs
 have the following format:
 
-**URL ::= Base-URL "/twirp/" [ Package "." ] Service "/" Method**
+```abnf
+URL ::= Base-URL [ Prefix ] "/" [ Package "." ] Service "/" Method
+```
 
 The Twirp wire protocol uses HTTP URLs to specify the RPC
 endpoints on the server for sending the requests. Such direct mapping
@@ -36,15 +38,14 @@ the following components.
   typically published via API documentation or service discovery.
   Currently, it should only contain URL `scheme` and `authority`. For
   example, "https://example.com".
-
+* **Prefix** is usually "/twirp", but it could be empty "", or an
+  arbitrary path like "/my/custom/prefix".
 * **Package** is the proto `package` name for an API, which is often
   considered as an API version. For example,
   `example.calendar.v1`. This component is omitted if the API
   definition doesn't have a package name.
-
 * **Service** is the proto `service` name for an API. For example,
   `CalendarService`.
-
 * **Method** is the proto `rpc` name for an API method. For example,
   `CreateEvent`.
 
@@ -145,30 +146,70 @@ Content-Length: 27
 {"message":"Hello, World!"}
 ```
 
+
 ## Errors
 
 Twirp error responses are always JSON-encoded, regardless of
 the request's Content-Type, with a corresponding
 `Content-Type: application/json` header. This ensures that
 the errors are human-readable in any setting.
 
-Twirp errors are a JSON object with three keys:
+Twirp errors are a JSON object with the keys:
 
 * **code**: One of the Twirp error codes as a string.
 * **msg**: A human-readable message describing the error
   as a string.
-* **meta**: An object with string keys and values holding
+* **meta**: (optional) An object with string values holding
   arbitrary additional metadata describing the error.
 
 Example:
+
+```json
+{
+  "code": "internal",
+  "msg": "Something went wrong"
+}
 ```
+
+Example with metadata:
+
+```json
 {
-    "code": "permission_denied",
-    "msg": "thou shall not pass",
-    "meta": {
-        "target": "Balrog"
-    }
+  "code": "permission_denied",
+  "msg": "Thou shall not pass",
+  "meta": {
+    "target": "Balrog",
+    "power": "999"
+  }
 }
 ```
 
-For more information, see https://github.com/twitchtv/twirp/wiki/Errors.
+### Error Codes
+
+Twirp errors always include an error code. This code is represented
+as a string and must be one of a fixed set of codes, listed in the
+table below. Each code has an associated HTTP Status Code. When a
+server responds with the given error code, it must set the
+corresponding HTTP Status Code for the response.
+
+| Twirp Error Code    | HTTP Status | Description
+| ------------------- | ----------- | -----------
+| canceled            | 408 | The operation was cancelled.
+| unknown             | 500 | An unknown error occurred. For example, this can be used when handling errors raised by APIs that do not return any error information.
+| invalid_argument    | 400 | The client specified an invalid argument. This indicates arguments that are invalid regardless of the state of the system (i.e. a malformed file name, required argument, number out of range, etc.).
+| malformed           | 400 | The client sent a message which could not be decoded. This may mean that the message was encoded improperly or that the client and server have incompatible message definitions.
+| deadline_exceeded   | 408 | Operation expired before completion. For operations that change the state of the system, this error may be returned even if the operation has completed successfully (timeout).
+| not_found           | 404 | Some requested entity was not found.
+| bad_route           | 404 | The requested URL path wasn't routable to a Twirp service and method. This is returned by generated server code and should not be returned by application code (use "not_found" or "unimplemented" instead).
+| already_exists      | 409 | An attempt to create an entity failed because one already exists.
+| permission_denied   | 403 | The caller does not have permission to execute the specified operation. It must not be used if the caller cannot be identified (use "unauthenticated" instead).
+| unauthenticated     | 401 | The request does not have valid authentication credentials for the operation.
+| resource_exhausted  | 429 | Some resource has been exhausted or rate-limited, perhaps a per-user quota, or perhaps the entire file system is out of space.
+| failed_precondition | 412 | The operation was rejected because the system is not in a state required for the operation's execution. For example, doing an rmdir operation on a directory that is non-empty, or on a non-directory object, or when having conflicting read-modify-write on the same resource.
+| aborted             | 409 | The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.
+| out_of_range        | 400 | The operation was attempted past the valid range. For example, seeking or reading past end of a paginated collection. Unlike "invalid_argument", this error indicates a problem that may be fixed if the system state changes (i.e. adding more items to the collection). There is a fair bit of overlap between "failed_precondition" and "out_of_range". We recommend using "out_of_range" (the more specific error) when it applies so that callers who are iterating through a space can easily look for an "out_of_range" error to detect when they are done.
+| unimplemented       | 501 | The operation is not implemented or not supported/enabled in this service.
+| internal            | 500 | When some invariants expected by the underlying system have been broken. In other words, something bad happened in the library or backend service. Twirp specific issues like wire and serialization problems are also reported as "internal" errors.
+| unavailable         | 503 | The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff.
+| dataloss            | 500 | The operation resulted in unrecoverable data loss or corruption.
+

clientcompat/internal/clientcompat/clientcompat.twirp.go

@@ -1,4 +1,4 @@
-# Code generated by protoc-gen-twirp_python v5.12.1, DO NOT EDIT.
+# Code generated by protoc-gen-twirp_python v7.0.0, DO NOT EDIT.
 # source: clientcompat.proto
 
 try:

clientcompat/pycompat/clientcompat_pb2_twirp.py

@@ -1,7 +1,7 @@
 ---
 id: "spec_v5"
 title: "Twirp Wire Protocol (v5)"
-sidebar_label: "Version 5 (Current)"
+sidebar_label: "Version 5 (Previous)"
 ---
 
 This document defines the initial Twirp wire protocol over HTTP.

docs/spec_v5.md

@@ -1,7 +1,7 @@
 ---
 id: "spec_v7"
 title: "Twirp Wire Protocol (v7)"
-sidebar_label: "Version 7 (Draft)"
+sidebar_label: "Version 7 (Current)"
 ---
 
 This document defines the Twirp wire protocol over HTTP. The
@@ -218,3 +218,10 @@ corresponding HTTP Status Code for the response.
 | dataloss            | 500 | The operation resulted in unrecoverable data loss or corruption.
 
 
+## Differences with v5
+
+Note v6 was a draft and never released. Twirp implementations supporting the protocol spec v5 should update directly to support v7.
+
+ * Twirp URLs in v5 could only have the "/twirp" prefix. In v7 they can have any arbitrary prefix or no prefix. See Go PR for reference: https://github.com/twitchtv/twirp/pull/264
+ * Error responses with code `resource_exhausted` in v5 had the HTTP status `403`. In v7 they have status `429`. See Go PR for reference: https://github.com/twitchtv/twirp/pull/270
+

docs/spec_v7.md

@@ -1,4 +1,4 @@
-# Code generated by protoc-gen-twirp_python v5.12.1, DO NOT EDIT.
+# Code generated by protoc-gen-twirp_python v7.0.0, DO NOT EDIT.
 # source: service.proto
 
 try:

example/service.twirp.go

@@ -13,4 +13,4 @@
 
 package gen
 
-const Version = "v5.12.1"
+const Version = "v7.0.0"

example/service_pb2_twirp.py

@@ -1,4 +1,4 @@
-# Code generated by protoc-gen-twirp_python v5.12.1, DO NOT EDIT.
+# Code generated by protoc-gen-twirp_python v7.0.0, DO NOT EDIT.
 # source: empty_service.proto
 
 try:

internal/gen/version.go

@@ -1,4 +1,4 @@
-# Code generated by protoc-gen-twirp_python v5.12.1, DO NOT EDIT.
+# Code generated by protoc-gen-twirp_python v7.0.0, DO NOT EDIT.
 # source: service.proto
 
 try: