v0.9.0: Rename RIDL "message" to "struct", schema "messages" to "type…

…s" (#171)

* RIDL: Rename "message" to "struct"

Split off #134 by @pkieltyka

* Schema: Rename "messages" to "types"

Split off #134 by @pkieltyka

* Fix tests

* Update .json schemas & provide migrate.js script

* Fix generating templates

* Regenerate examples

* Re-add two template functions to docs

CHANGELOG.md

@@ -0,0 +1,161 @@
+# webrpc v0.9.0
+
+Towards reaching webrpc@v1.0.0, we have decided to make some breaking changes to webrpc schema and RIDL file format.
+
+## Breaking changes
+
+### RIDL v0.9.0 changes
+
+Keyword "message" was renamed to "struct".
+
+```diff
+ webrpc = v1
+
+ name = your-app
+ version = v0.1.0
+
+- message User
++ struct User
+   - id: uint64
+   - username: string
+   - createdAt?: timestamp
+```
+
+### JSON schema v0.9.0 changes
+
+- Field "messages" was renamed to "types"
+- Field "type" was renamed to "kind"
+
+```diff
+ {
+   "webrpc": "v1",
+   "name": "Test",
+   "version": "v0.0.1",
+   "imports": [],
+-  "messages": [
++  "types": [
+   {
+     "name": "Status",
+-    "type": "enum",
++    "kind": "enum",
+     "fields": [
+     {
+       "name": "AVAILABLE",
+-      "type": "uint32",
+-      "optional": false,
+       "value": "0",
+-      "meta": null
+     },
+     {
+       "name": "NOT_AVAILABLE",
+-      "type": "uint32",
+-      "optional": false,
+       "value": "1",
+-      "meta": null
+     }
+   },
+   {
+    "name": "Empty",
+-   "type": "struct",
++   "kind": "struct",
+-   "fields": null
+   }]
+ }
+```
+
+### Template changes
+
+You might see the following error when running your webrpc generator templates against webrpc-gen@v0.9.0+:
+
+```
+template: main.go.tmpl:88:57: executing "main" at <.Messages>: can't evaluate field Messages in type struct { *schema.WebRPCSchema; SchemaHash string; WebrpcGenVersion string; WebrpcGenCommand string; WebrpcTarget string; Opts map[string]interface {} }
+```
+
+To fix this, rename `{{.Messages}}` variable to `{{.Types}}` in your `*.go.tmpl` template files.
+
+## Migration guide
+
+### RIDL v0.9.0 migration guide
+
+Run this command to migrate your RIDL files to webrpc@v0.9.0+:
+
+```bash
+#!/bin/bash
+
+find . -name '*.ridl' -exec sed -i -e 's/^message /struct /g' {} \;
+```
+
+### JSON schema v0.9.0 migration guide
+
+Run this Node.js script to migrate your `*webrpc.json` schema files to webrpc@v0.9.0+:
+
+`node migrate.js schema.webrpc.json`
+
+Contents of `migrate.js` file:
+```javascript
+const fs = require("fs");
+
+if (process.argv.length != 3) {
+  throw Error(`Usage: node ${process.argv[1]} <webrpc-schema.json>`);
+}
+
+const filePath = process.argv[2];
+
+console.log(filePath);
+
+fs.readFile(filePath, "utf8", (e, data) => {
+  if (e) {
+    throw e;
+  }
+
+  let schema = JSON.parse(data);
+  schema = {
+    webrpc: schema.webrpc,
+    name: schema.name,
+    version: schema.version,
+    types: schema.messages.map((orig) => {
+      let type = {
+        name: orig.name,
+        kind: orig.type,
+        fields: orig.fields,
+      };
+
+      if (type.kind == "enum") {
+        type = {
+          name: orig.name,
+          kind: orig.type,
+          type: orig.fields[0].type,
+          fields: orig.fields.map((field) => {
+            return { name: field.name, value: field.value };
+          }),
+        };
+      }
+      return type;
+    }),
+    services: schema.services,
+  };
+
+  schema.types = fs.writeFile(
+    filePath,
+    JSON.stringify(schema, null, "\t"),
+    (err) => {
+      if (err) {
+        console.error(err);
+        console.log(schema);
+      }
+    }
+  );
+});
+```
+
+### Generator templates v0.9.0 migration guide
+
+Run this command to migrate your `.go.tmpl` templates to webrpc@v0.9.0+:
+
+```bash
+#!/bin/bash
+
+find . -name '*.go.tmpl' -exec sed -i -e 's/\.Messages/.Types/g' {} \;
+find . -name '*.go.tmpl' -exec sed -i -e 's/"Messages"/"Types"/g' {} \;
+```
+

README.md

@@ -56,12 +56,12 @@ webrpc = v1
 name = your-app
 version = v0.1.0
 
-message User
+struct User
   - id: uint64
   - username: string
   - createdAt?: timestamp
 
-message UsersQueryFilter
+struct UsersQueryFilter
   - page?: uint32
   - name?: string
   - location?: string
@@ -132,7 +132,7 @@ of cases that this would be a bottleneck or costly tradeoff.
 
 webrpc is heavily inspired by gRPC and Twirp. It is architecturally the same and has a similar
 workflow, but simpler. In fact, the webrpc schema is similar in design to protobuf, as
-in we have messages and rpc methods, but the type system is arguably more flexible and
+in we have messages (structs) and RPC methods, but the type system is arguably more flexible and
 code-gen tooling is simpler. The [webrpc schema](./schema/README.md) is a documentation-like
 language for describing a server's api interface and the type system within is inspired by Go,
 Typescript and WASM.

_examples/golang-basics/README.md

@@ -13,7 +13,7 @@ you can also write your schema in JSON format like so, [./example.webrpc.json](.
 2. Design your schema file and think about the methods calls clients will need to make
 to your service
 3. Write the "services" section of the schema file
-4. From the inputs and outputs for the function definitions, start writing the "messages"
+4. From the inputs and outputs for the function definitions, start writing the "structs"
 section of the data types needed in your program.
 5. Run the code generator to build the server and client:
   * `webrpc-gen -schema=example.ridl -target=golang -pkg=main -server -client -out=./example.gen.go`

_examples/golang-basics/example.ridl

@@ -9,10 +9,10 @@ enum Kind: uint32
   - ADMIN
 
 
-message Empty
+struct Empty
 
 
-message User
+struct User
   - id: uint64
     + json = id
     + go.field.name = ID
@@ -25,15 +25,15 @@ message User
   - role: string
     + go.tag.db = -
 
-message SearchFilter
+struct SearchFilter
   - q: string
 
-message Version
+struct Version
   - webrpcVersion: string
   - schemaVersion: string
   - schemaHash: string
 
-message ComplexType
+struct ComplexType
   - meta: map<string,any>
   - metaNestedExample: map<string,map<string,uint32>>
   - namesList: []string