Skip to content

Commit 556dabc

Browse files
VojtechVitekVojtechVitek
authored
Merge pull request #3 from webrpc/feature/v0-ignore-bignum
v0 Dart client generation
2 parents 494eec2 + bccb2a4 commit 556dabc

File tree

169 files changed

+8641
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

169 files changed

+8641
-1
lines changed

‎.github/workflows/ci.yml

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Test
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
pull_request:
8+
branches:
9+
- "**"
10+
11+
jobs:
12+
get-webrpc:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v3
16+
17+
- name: Install webrpc-gen
18+
run: |
19+
curl -o ./webrpc-gen -fLJO https://github.com/webrpc/webrpc/releases/download/v0.18.0/webrpc-gen.linux-amd64
20+
chmod +x ./webrpc-gen
21+
echo $PWD >> $GITHUB_PATH
22+
23+
webrpc-tests:
24+
runs-on: ubuntu-latest
25+
strategy:
26+
matrix:
27+
webrpc-version: [v0.18.0]
28+
dart-version: [3.1]
29+
30+
steps:
31+
- uses: actions/checkout@v3
32+
33+
- name: Set up webrpc binary cache folder
34+
uses: actions/cache@v3
35+
with:
36+
key: webrpc-binaries
37+
path: tests/.tmp
38+
39+
- uses: dart-lang/setup-dart@v1
40+
with:
41+
sdk: ${{ matrix.dart-version }}
42+
43+
- name: Download webrpc binaries
44+
working-directory: ./tests
45+
run: ./scripts/download.sh ${{ matrix.webrpc-version }} .tmp/
46+
47+
- name: Export path of webrpc binaries
48+
working-directory: ./tests
49+
run: echo "$PWD/.tmp" >> $GITHUB_PATH
50+
51+
- name: Install Dart dependencies
52+
working-directory: ./tests
53+
run: dart pub get
54+
55+
- name: Run interoperability tests
56+
working-directory: ./tests
57+
run: ./scripts/test.sh

‎.vscode/launch.json

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{
2+
// Use IntelliSense to learn about possible attributes.
3+
// Hover to view descriptions of existing attributes.
4+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"name": "Ex. frontend (main)",
9+
"request": "launch",
10+
"type": "dart",
11+
"program": "${workspaceFolder}/_examples/flutter-go/flutter_app/lib/main.dart",
12+
"args": [
13+
"--dart-define=SERVICE=real",
14+
"--dart-define=SERVICE_HOSTNAME=http://localhost:3333",
15+
"--web-browser-flag=--disable-web-security"
16+
]
17+
},
18+
{
19+
"name": "Ex. frontend (mocked)",
20+
"request": "launch",
21+
"type": "dart",
22+
"program": "${workspaceFolder}/_examples/flutter-go/flutter_app/lib/main.dart",
23+
"args": [
24+
"--dart-define=SERVICE=mock",
25+
"--web-browser-flag=--disable-web-security"
26+
]
27+
},
28+
{
29+
"name": "Ex. frontend tests",
30+
"type": "dart",
31+
"request": "launch",
32+
"program": "${workspaceFolder}/_examples/flutter-go/flutter_app/test/",
33+
"args": [
34+
"--dart-define=SERVICE=mock",
35+
]
36+
},
37+
{
38+
"name": "Ex. backend (go_server)",
39+
"request": "launch",
40+
"type": "go",
41+
"program": "${workspaceFolder}/_examples/flutter-go/go_server/main.go",
42+
"env": {
43+
"SERVICE_PORT": "3333"
44+
}
45+
},
46+
]
47+
}

‎LICENSE

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Copyright (c) 2019-present https://github.com/webrpc authors
2+
3+
MIT License
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy of
6+
this software and associated documentation files (the "Software"), to deal in
7+
the Software without restriction, including without limitation the rights to
8+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9+
the Software, and to permit persons to whom the Software is furnished to do so,
10+
subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

+114-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,114 @@
1-
# gen-dart
1+
# gen-dart
2+
3+
webrpc-gen Dart templates
4+
===============================
5+
6+
This repo contains the templates used by the `webrpc-gen` cli to code-generate
7+
webrpc Dart server and client code.
8+
9+
This generator, from a webrpc schema/design file will code-generate:
10+
11+
1. Client -- an isomorphic/universal Dart client to speak to a webrpc server using the
12+
provided schema. This client is compatible with any webrpc server language (ie. Go, nodejs, etc.).
13+
14+
2. Server -- not yet supported
15+
16+
## Dependencies
17+
The generated client requires the standard `http` package to function. Add it to your pubspec.yaml
18+
in your Dart or Flutter project
19+
20+
```
21+
dependencies:
22+
# ... other dependencies
23+
http: ^1.1.0
24+
```
25+
26+
## Usage
27+
28+
```
29+
webrpc-gen -schema=example.ridl -target=dart -client -out=./example.gen.dart
30+
```
31+
32+
or
33+
34+
```
35+
webrpc-gen -schema=example.ridl -target=github.com/webrpc/[email protected] -client -out=./example.gen.dart
36+
```
37+
38+
or
39+
40+
```
41+
webrpc-gen -schema=example.ridl -target=./local-templates-on-disk -client -out=./example.gen.dart
42+
```
43+
44+
As you can see, the `-target` supports default `dart`, any git URI, or a local folder
45+
46+
### Set custom template variables
47+
Change any of the following values by passing `-option="Value"` CLI flag to `webrpc-gen`.
48+
49+
| webrpc-gen -option | Description | Default value |
50+
|----------------------|----------------------------|----------------------------|
51+
| `-client` | generate client code | unset (`false`) |
52+
| `-server` | generate server code | unset (`false`) |
53+
54+
### Avoid using Records
55+
Because Dart [Records do not retain runtime information about their structure](https://github.com/dart-lang/language/issues/2826), it's impossible
56+
to reliably convert them to and from JSON. For this reason, we strongly advise against
57+
using Records in schema objects that have an `any` type (which maps to `dynamic` in Dart). In fact,
58+
you probably should not ever use the `any` type in your schema because it has ambigious
59+
structure which makes its structure meaningless on the other end of the wire. If you need a truly
60+
unstructured object, consider defining an internal convention and declaring it as a string in the schema.
61+
62+
### Handle 64-bit numbers yourself
63+
Numbers (`double`, `num`, `int`) in Dart can have up to 64 bits of width. However, if you are
64+
using Flutter and building for web, [numbers are limited to ~53 bits](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER). In brief,
65+
the consequence of this is that if your server sends a JSON number that is too big, it may be
66+
truncated - the value will change - according to the platform (language + architecture) being used.
67+
So, if you expected to use "wide" numbers (less than -(2^53 -1) or more than 2^53 - 1), you
68+
should package those numbers as a string and use the appropriate tools to handle them inside
69+
your app (such as `BigInt` in Dart).
70+
71+
## CONTRIBUTE
72+
73+
### Setup
74+
Install Dart or Flutter. Ensure your version matches the `sdk` version specified in [tests/pubspec.yaml](tests/pubspec.yaml).
75+
76+
Fork this repo.
77+
78+
Run the test scripts to ensure everything is set up correctly.
79+
```bash
80+
cd tests
81+
./scripts/download.sh v0.17.2 .tmp/
82+
./scripts/test.sh
83+
```
84+
85+
Generated code will be written to [tests/lib/client.dart](tests/lib/client.dart)
86+
87+
### Make changes
88+
Refer to the [webrpc generator README](https://github.com/webrpc/webrpc/tree/master/gen) for help on syntax.
89+
In brief, start in [main.go.tmpl] and traverse the template tree by going to the template file
90+
named by `{{template "templateName" <args>}}`, e.g. "templateName.go.tmpl".
91+
92+
### (Update and) Run tests
93+
Following the typical structure for a Dart package, tests are located in the aptly named
94+
[tests/test/](tests/test/).
95+
96+
### Working with a local version of webrpc?
97+
If you are working with a local version of the base `webrpc` repo, build the generator and test server scripts
98+
there
99+
100+
```bash
101+
cd path/to/webrpc
102+
make build build-test
103+
```
104+
105+
and pass the `webrpc/bin` directory to [tests/scripts/test.sh](tests/scripts/test.sh)
106+
107+
```bash
108+
cd tests
109+
./scripts/test.sh -r path/to/webrpc/bin
110+
```
111+
112+
## LICENSE
113+
114+
[MIT LICENSE](./LICENSE)

‎_examples/flutter-go/.gitignore

Whitespace-only changes.

‎_examples/flutter-go/README.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# flutter-go
2+
An example full-stack app using Flutter as the frontend and a minimal golang server as the backend.
3+
4+
## Structure
5+
6+
| Path | Description |
7+
| --------------------------------------------------- | ---------- |
8+
| [service.ridl](./service.ridl) | webrpc service schema (types, endpoints, and errors); shared between client and server. |
9+
| [flutter_app/](./flutter_app/) | frontend Flutter app (tested on Web only) |
10+
| [flutter_app/lib/main.dart](./flutter_app/lib/main.dart) | flutter app entry-point |
11+
| [flutter_app/lib/generated/sdk.dart](./flutter_app/lib/generated/sdk.dart) | generated client code |
12+
| [flutter_app/lib/dev/mock_sdk.dart](./flutter_app/lib/dev/mock_sdk.dart) | example of mocking the service for development and testing |
13+
| [flutter_app/lib/src/sample_feature/*](./flutter_app/lib/src/sample_feature/) | widgets using the generated client |
14+
| [flutter_app/test/widget_test.dart](./flutter_app/test/widget_test.dart) | tests of widgets using the generated client |
15+
| [go_server/](./go_server/) | Backend server |
16+
17+
## Try it out
18+
Start the server (after installing Go).
19+
```bash
20+
cd go_server
21+
SERVICE_PORT=3333 go run main.go
22+
```
23+
24+
Start the client (after installing Flutter).
25+
```bash
26+
cd flutter_app
27+
flutter run -d chrome --dart-define=SERVICE=real --dart-define=SERVICE_HOSTNAME=http://localhost:3333
28+
```
29+
30+
## Make changes
31+
Try updating the service schema and re-generating the client and server code.
32+
33+
To generate the client
34+
```bash
35+
path/to/webrpc-gen -schema=./service.ridl -target=../../ -client -out=flutter_app/lib/generated/sdk.dart
36+
```
37+
38+
To generate the server
39+
```bash
40+
path/to/webrpc-gen -schema=./service.ridl -target=golang -server -out=go_server/proto/server.gen.go
41+
```

‎_examples/flutter-go/flutter_app/.gitignore

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Miscellaneous
2+
*.class
3+
*.log
4+
*.pyc
5+
*.swp
6+
.DS_Store
7+
.atom/
8+
.buildlog/
9+
.history
10+
.svn/
11+
migrate_working_dir/
12+
13+
# IntelliJ related
14+
*.iml
15+
*.ipr
16+
*.iws
17+
.idea/
18+
19+
# The .vscode folder contains launch configuration and tasks you configure in
20+
# VS Code which you may wish to be included in version control, so this line
21+
# is commented out by default.
22+
#.vscode/
23+
24+
# Flutter/Dart/Pub related
25+
**/doc/api/
26+
**/ios/Flutter/.last_build_id
27+
.dart_tool/
28+
.flutter-plugins
29+
.flutter-plugins-dependencies
30+
.packages
31+
.pub-cache/
32+
.pub/
33+
/build/
34+
35+
# Symbolication related
36+
app.*.symbols
37+
38+
# Obfuscation related
39+
app.*.map.json
40+
41+
# Android Studio will place build artifacts here
42+
/android/app/debug
43+
/android/app/profile
44+
/android/app/release

‎_examples/flutter-go/flutter_app/README.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# flutter_app
2+
3+
A new Flutter project.
4+
5+
## Getting Started
6+
7+
This project is a starting point for a Flutter application that follows the
8+
[simple app state management
9+
tutorial](https://flutter.dev/docs/development/data-and-backend/state-mgmt/simple).
10+
11+
For help getting started with Flutter development, view the
12+
[online documentation](https://flutter.dev/docs), which offers tutorials,
13+
samples, guidance on mobile development, and a full API reference.
14+
15+
## Assets
16+
17+
The `assets` directory houses images, fonts, and any other files you want to
18+
include with your application.
19+
20+
The `assets/images` directory contains [resolution-aware
21+
images](https://flutter.dev/docs/development/ui/assets-and-images#resolution-aware).
22+
23+
## Localization
24+
25+
This project generates localized messages based on arb files found in
26+
the `lib/src/localization` directory.
27+
28+
To support additional languages, please visit the tutorial on
29+
[Internationalizing Flutter
30+
apps](https://flutter.dev/docs/development/accessibility-and-localization/internationalization)

‎_examples/flutter-go/flutter_app/analysis_options.yaml

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# This file configures the analyzer, which statically analyzes Dart code to
2+
# check for errors, warnings, and lints.
3+
#
4+
# The issues identified by the analyzer are surfaced in the UI of Dart-enabled
5+
# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be
6+
# invoked from the command line by running `flutter analyze`.
7+
8+
# The following line activates a set of recommended lints for Flutter apps,
9+
# packages, and plugins designed to encourage good coding practices.
10+
include: package:flutter_lints/flutter.yaml
11+
12+
linter:
13+
# The lint rules applied to this project can be customized in the
14+
# section below to disable rules from the `package:flutter_lints/flutter.yaml`
15+
# included above or to enable additional rules. A list of all available lints
16+
# and their documentation is published at https://dart.dev/lints.
17+
#
18+
# Instead of disabling a lint rule for the entire project in the
19+
# section below, it can also be suppressed for a single line of code
20+
# or a specific dart file by using the `// ignore: name_of_lint` and
21+
# `// ignore_for_file: name_of_lint` syntax on the line or in the file
22+
# producing the lint.
23+
rules:
24+
# avoid_print: false # Uncomment to disable the `avoid_print` rule
25+
# prefer_single_quotes: true # Uncomment to enable the `prefer_single_quotes` rule
26+
27+
# Additional information about this file can be found at
28+
# https://dart.dev/guides/language/analysis-options

0 commit comments

Comments
 (0)