Releases: webrpc/webrpc
v0.11.2
Changelog
- ed201f3: Fix examples after introducing customer webrpc errors (#209) (@LukasJenicek)
- 94335ea: Template generator: Implement generic array functions (#210) (@VojtechVitek)
Docker
docker pull ghcr.io/webrpc/webrpc-gen:v0.11.2
Example: docker run -v $PWD:$PWD ghcr.io/webrpc/webrpc-gen:v0.11.2 -schema=$PWD/api.ridl -target=golang
Homebrew
brew tap webrpc/tap
brew install webrpc-gen
Build from source
go install -ldflags="-s -w -X github.com/webrpc/webrpc.VERSION=v0.11.2" github.com/webrpc/webrpc/cmd/webrpc-gen@v0.11.2
Download binaries
macOS: amd64, arm64 (Apple Silicon)
Linux: amd64, arm64
Windows: amd64, arm64
v0.11.1
Changelog
- 0d39e64: Add `webrpc-test -printJSON' (#206) (@VojtechVitek)
- 9f39e57: Add release notes / changelog for v0.11.0 (#201) (@VojtechVitek)
- cbf618c: Bump version to v0.12.x-dev (@VojtechVitek)
- d31c49f: Fix windows path handling (#202) (@pieter-lazzaro)
- 3d8704f: Implement `webrpc-test -waitForServer -timeout=10s' (#208) (@VojtechVitek)
- 664a6c1: Regenerate examples (@VojtechVitek)
- bdcd995: Regenerate examples (latest TypeScript example) (#207) (@VojtechVitek)
Docker
docker pull ghcr.io/webrpc/webrpc-gen:v0.11.1
Example: docker run -v $PWD:$PWD ghcr.io/webrpc/webrpc-gen:v0.11.1 -schema=$PWD/api.ridl -target=golang
Homebrew
brew tap webrpc/tap
brew install webrpc-gen
Build from source
go install -ldflags="-s -w -X github.com/webrpc/webrpc.VERSION=v0.11.1" github.com/webrpc/webrpc/cmd/webrpc-gen@v0.11.1
Download binaries
macOS: amd64, arm64 (Apple Silicon)
Linux: amd64, arm64
Windows: amd64, arm64
v0.11.0 schema errors
Feature: Define webrpc schema errors
You can now define your own custom schema errors in RIDL file, for example:
error 1 Unauthorized "unauthorized" HTTP 401
error 2 ExpiredToken "expired token" HTTP 401
error 3 InvalidToken "invalid token" HTTP 401
error 4 Deactivated "account deactivated" HTTP 403
error 5 ConfirmAccount "confirm your email" HTTP 403
error 6 AccessDenied "access denied" HTTP 403
error 7 MissingArgument "missing argument" HTTP 400
error 8 UnexpectedValue "unexpected value" HTTP 400
error 100 RateLimited "too many requests" HTTP 429
error 101 DatabaseDown "service outage" HTTP 503
error 102 ElasticDown "search is degraded" HTTP 503
error 103 NotImplemented "not implemented" HTTP 501
error 200 UserNotFound "user not found"
error 201 UserBusy "user busy"
error 202 InvalidUsername "invalid username"
error 300 FileTooBig "file is too big (max 1GB)"
error 301 FileInfected "file is infected"
error 302 FileType "unsupported file type"
Note: Unless specified, the default HTTP status for webrpc errors is HTTP 400
.
typescript@v0.11.0 breaking changes
- All errors thrown by webrpc client are now instance of
WebrpcError
, which extends JavaScriptError
. No need to re-throw errors anymore. error.msg
error.message
- by default, the error messages are "human-friendly", they don't contain any details about the backend error cause
- underlying backend error (for developers) is optionally available as
error.cause?
error.code
orerror.message
can be used as input for user-friendly error i18n translations
You can now check for explicit error class instance (as defined in RIDL schema) or against a generic WebrpcError
class.
try {
const resp = await testApiClient.getUser();
// setUser(resp.user)
} catch (error) {
if (error instanceof RateLimitedError) {
// retry with back-off time
}
if (error instanceof UnauthorizedError) {
// render sign-in page
}
if (error instanceof WebrpcError) {
console.log(error.status) // print response HTTP status code (ie. 4xx or 5xx)
console.log(error.code) // print unique schema error code; generic endpoint errors are 0
console.log(error.message) // print error message
console.log(error.cause) // print the underlying backend error -- ie. "DB error" - useful for debugging / reporting to Sentry
}
// setError(error.message)
}
golang@v0.11.0 breaking changes
Note: You can turn on -legacyErrors=true
flag on golang generator (ie. webrpc-gen -target=golang -legacyErrors=true -pkg=proto
) in order to preserve the deprecated functions and sentinel errors (see below). This will allow you to migrate your codebase to the new custom schema errors gradually.
The following werbrpc error functions and sentinel errors are now deprecated or removed:
proto.WrapError() // Deprecated.
proto.Errorf() // Deprecated.
proto.HTTPStatusFromErrorCode()
proto.IsErrorCode()
proto.ErrCanceled // Deprecated.
proto.ErrUnknown // Deprecated.
proto.ErrFail // Deprecated.
proto.ErrInvalidArgument // Deprecated.
proto.ErrDeadlineExceeded // Deprecated.
proto.ErrNotFound // Deprecated.
proto.ErrBadRoute // Deprecated.
proto.ErrAlreadyExists // Deprecated.
proto.ErrPermissionDenied // Deprecated.
proto.ErrUnauthenticated // Deprecated.
proto.ErrResourceExhausted // Deprecated.
proto.ErrFailedPrecondition // Deprecated.
proto.ErrAborted // Deprecated.
proto.ErrOutOfRange // Deprecated.
proto.ErrUnimplemented // Deprecated.
proto.ErrInternal // Deprecated.
proto.ErrUnavailable // Deprecated.
proto.ErrDataLoss // Deprecated.
proto.ErrNone // Deprecated.
The schema errors can now be returned from the RPC endpoints via:
func (s *RPC) RemoveUser(ctx context.Context, userID int64) (bool, error) {
r, _ := ctx.Value(proto.HTTPRequestCtxKey).(*http.Request)
if s.IsRateLimited(r) {
- return false, proto.Errorf(proto.ErrUnavailable, "rate limited")
+ return false, proto.ErrRateLimited // HTTP 429 per RIDL schema
}
_, err := s.DB.RemoveUser(ctx, userID)
if err != nil {
if errors.Is(err, pgx.ErrNoRows) {
- return false, proto.Errorf(proto.ErrNotFound, "no such user(%v)", userID)
+ return false, proto.ErrUserNotFound
}
- return false, proto.WrapError(proto.ErrInternal, err, "")
+ return false, proto.ErrorWithCause(proto.ErrDatabaseDown, err)
}
return true, nil
}
You can also return any other Go error and webrpc will render generic proto.ErrWebrpcEndpoint
error automatically along with HTTP 400
status code.
return fmt.Errorf("some error")
The RPC client(s) can now assert the schema error type by their unique error code:
if err, ok := rpc.RemoveUser(ctx, userID); err != nil {
if errors.Is(proto.ErrRateLimited) {
// slow down; retry with back-off strategy
}
if errors.Is(proto.ErrUserNotFound) {
// handle
}
// etc.
}
Changelog
- e442000: Bump to v0.11.0 (@VojtechVitek)
- 71d6e69: Bump to v0.11.0 - regenerate examples (#199) (@VojtechVitek)
- 1e5d18b: Update links to migration guide (@VojtechVitek)
- bf6dd73: Update to latest Go and TS gens with schema support (#200) (@VojtechVitek)
- 503d4b5: Add Go 1.20 to CI matrix (#195) (@VojtechVitek)
- a6758ac: Add built-in webrpc errors (#196) (@VojtechVitek)
- ee01a05: Add interoperability test for error cause (#198) (@VojtechVitek)
- e8a5e62: Schema errors: HTTP status code must be between 400-599 (#197) (@VojtechVitek)
- a6758ac: Add built-in webrpc errors (#196) (@VojtechVitek)
Docker
docker pull ghcr.io/webrpc/webrpc-gen:v0.11.0
Example: docker run -v $PWD:$PWD ghcr.io/webrpc/webrpc-gen:v0.11.0 -schema=$PWD/api.ridl -target=golang
Homebrew
brew tap webrpc/tap
brew install webrpc-gen
Build from source
go install -ldflags="-s -w -X github.com/webrpc/webrpc.VERSION=v0.11.0" github.com/webrpc/webrpc/cmd/webrpc-gen@v0.11.0
Download binaries
macOS: amd64, arm64 (Apple Silicon)
Linux: amd64, arm64
Windows: amd64, arm64
v0.10.0 interoperability tests
Tested with the following targets:
Added new interoperability tests
We have defined a new interoperability test suite implementing the following schema:
webrpc = v1
name = Test
version = v0.10.0
service TestApi
- GetEmpty()
- GetError()
- GetOne() => (one: Simple)
- SendOne(one: Simple)
- GetMulti() => (one: Simple, two: Simple, three: Simple)
- SendMulti(one: Simple, two: Simple, three: Simple)
- GetComplex() => (complex: Complex)
- SendComplex(complex: Complex)
All generators are expected to implement TestApi schema and run client/server interoperability tests against a reference webrpc-test binaries).
For more info, see typescript or golang tests.
Breaking changes in ridl package Go API
-func NewParser(r *schema.Reader) *Parser
+func NewParser(fsys fs.FS, path string) *Parser
Breaking changes in gen package Go API
- func NewTemplateSource(proto *schema.WebRPCSchema, target string, config *Config) (*TemplateSource, error)
+ func NewTemplateSource(target string, config *Config) (*TemplateSource, error)
Changelog
- 4fed3b0: Accept io.FS in RIDL parser (#178) (@VojtechVitek)
- aabb887: Bump to webrpc@v0.10.0 (#182) (@VojtechVitek)
- e7fd8ea: Fix CI: Regenerate all _examples/ (#177) (@VojtechVitek)
- 3f2508a: Improve interoperability test suite: Add more RPC methods to TestApi (#181) (@VojtechVitek)
- 4326cfc: Invalidate Github Actions cache every day (#180) (@VojtechVitek)
- 92e3dbe: v0.9.0 changelog: Document ENUM type JSON schema changes (#179) (@VojtechVitek)
Docker
docker pull ghcr.io/webrpc/webrpc-gen:v0.10.0
Example: docker run -v $PWD:$PWD ghcr.io/webrpc/webrpc-gen:v0.10.0 -schema=$PWD/api.ridl -target=golang
Homebrew
brew tap webrpc/tap
brew install webrpc-gen
Build from source
go install -ldflags="-s -w -X github.com/webrpc/webrpc.VERSION=v0.10.0" github.com/webrpc/webrpc/cmd/webrpc-gen@v0.10.0
Download binaries
macOS: amd64, arm64 (Apple Silicon)
Linux: amd64, arm64
Windows: amd64, arm64
v0.9.1
- Allow webrpc-test binary to print out ridl scheme
v0.9.0 RIDL updates
Breaking changes in v0.9.0
See https://github.com/webrpc/webrpc/blob/master/CHANGELOG.md#ridl-v090-changes
Migrate to RIDL v0.9.0
TL;DR run find . -name '*.ridl' -exec sed -i -e 's/^message /struct /g' {} \;
See https://github.com/webrpc/webrpc/blob/master/CHANGELOG.md#ridl-v090-migration-guide
Changelog
- 80d284b: Improve testing suite (#174) (@LukasJenicek)
- 30ed299: Internal renaming (#168) (@VojtechVitek)
- 945fe4c: Move VERSION to top-level package (#169) (@VojtechVitek)
- 5e6d1b8: v0.9.0: Fix non-deterministic schema hash (#172) (@VojtechVitek)
- 25708e7: v0.9.0: Rename RIDL "message" to "struct", schema "messages" to "types" (#171) (@VojtechVitek)
Docker
docker pull ghcr.io/webrpc/webrpc-gen:v0.9.0
Example: docker run -v $PWD:$PWD ghcr.io/webrpc/webrpc-gen:v0.9.0 -schema=$PWD/api.ridl -target=golang
Homebrew
brew tap webrpc/tap
brew install webrpc-gen
Build from source
go install -ldflags="-s -w -X github.com/webrpc/webrpc.VERSION=v0.9.0" github.com/webrpc/webrpc/cmd/webrpc-gen@v0.9.0
Download binaries
macOS: amd64, arm64 (Apple Silicon)
Linux: amd64, arm64
Windows: amd64, arm64
v0.8.3
Changelog
- 918512a: Bump decode-uri-component from 0.2.0 to 0.2.2 in /_examples/node-ts/webapp (#156) (@dependabot[bot])
- 3ea8210: Bump express from 4.16.4 to 4.17.3 in /_examples/node-ts/server (#159) (@dependabot[bot])
- a55acf6: Bump qs from 6.5.2 to 6.5.3 in /_examples/node-ts/webapp (#158) (@dependabot[bot])
- d84328a: Github CI: Run client-server interoperability test (golang@latest <-> golang@latest) (#163) (@VojtechVitek)
- 935d0a4: Github actions: Cache webrpc templates between CI jobs (#166) (@VojtechVitek)
- 0b3c7e2: Go releaser: Build webrpc-test binary (#162) (@VojtechVitek)
- d4cca79: Relax template cache invalidation (#165) (@VojtechVitek)
- fdd8f05: Update testing suite (#157) (@LukasJenicek)
- 9bb71d0: Update the new testing suite (#161) (@VojtechVitek)
Docker
docker pull ghcr.io/webrpc/webrpc-gen:v0.8.3
Example: docker run -v $PWD:$PWD ghcr.io/webrpc/webrpc-gen:v0.8.3 -schema=$PWD/api.ridl -target=golang
Homebrew
brew tap webrpc/tap
brew install webrpc-gen
Build from source
go install -ldflags="-s -w -X github.com/webrpc/webrpc/gen.VERSION=v0.8.3" github.com/webrpc/webrpc/cmd/webrpc-gen@v0.8.3
Download binaries
macOS: amd64, arm64 (Apple Silicon)
Linux: amd64, arm64
Windows: amd64, arm64
v0.8.2
Changelog
- aa4402f: update print summary layout (@pkieltyka)
Docker
docker run ghcr.io/webrpc/webrpc-gen:v0.8.2
Homebrew
brew tap webrpc/tap
brew install webrpc-gen
Build from source
go install -ldflags="-s -w -X github.com/webrpc/webrpc/gen.VERSION=v0.8.2" github.com/webrpc/webrpc/cmd/webrpc-gen@v0.8.2
Download binaries
macOS: amd64, arm64 (Apple Silicon)
Linux: amd64, arm64
Windows: amd64, arm64
v0.8.1
Changelog
- 042aa56: Bump minimatch from 3.0.4 to 3.1.2 in /_examples/node-ts/webapp (#151) (@dependabot[bot])
- e4fadb8: Examples: Print available commands when invoking make (#152) (@VojtechVitek)
- 5f36bea: Improve release notes (#150) (@VojtechVitek)
- 67409a6: print summary after code generation (#155) (@pkieltyka)
Docker
docker run ghcr.io/webrpc/webrpc-gen:v0.8.1
Homebrew
brew tap webrpc/tap
brew install webrpc-gen
Build from source
go install -ldflags="-s -w -X github.com/webrpc/webrpc/gen.VERSION=v0.8.1" github.com/webrpc/webrpc/cmd/webrpc-gen@v0.8.1
Download binaries
macOS: amd64, arm64 (Apple Silicon)
Linux: amd64, arm64
Windows: amd64, arm64
v0.8.0
Docker
docker run ghcr.io/webrpc/webrpc-gen:v0.8.0
Homebrew
brew install webrpc/tap/webrpc-gen
Build & install from source manually
go install github.com/webrpc/webrpc/cmd/webrpc-gen
Changelog
- 3b543f4: README: Add Install steps, improve Getting started and Release notes (#146) (@VojtechVitek)
- e4b2391: webrpc-gen v0.8.0 - Add sort, trimPrefix and trimSuffix template functions (#147) (@VojtechVitek)
- 155fd9b: webrpc-gen v0.8.0: Implement template arrays (#149) (@VojtechVitek)