Merge branch 'release/v0.2.0'

Author: jirenius

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+github: [jirenius]
+custom: ["https://www.paypal.me/jirenius"]

.travis.yml

@@ -1,18 +1,16 @@
 language: go
 go:
-- 1.10.x
-- 1.11.x
+- 1.13.x
 - 1.12.x
+- 1.11.x
+before_install:
+- if [[ "$TRAVIS_GO_VERSION" =~ ^1\.11\. ]]; then export GO111MODULE=off; fi
 install:
 - go get -t ./...
-- go get github.com/mattn/goveralls
-- go get golang.org/x/lint/golint
-- go get github.com/client9/misspell/cmd/misspell
+- if [[ "$TRAVIS_GO_VERSION" =~ ^1\.13\. ]]; then ./scripts/install-checks.sh; fi
 before_script:
-- $(exit $(go fmt ./... | wc -l))
-- go vet ./...
-- golint ./...
-- misspell -error -locale US ./...
+- if [[ "$TRAVIS_GO_VERSION" =~ ^1\.13\. ]]; then ./scripts/check.sh; fi
+- go build
 - go build $(go list ./examples/...)
 script:
-- if [[ "$TRAVIS_GO_VERSION" =~ ^1\.12\. ]]; then ./scripts/cover.sh TRAVIS; else go test -i -race ./...; fi
+- if [[ "$TRAVIS_GO_VERSION" =~ ^1\.13\. ]]; then ./scripts/cover.sh TRAVIS; else go test -i -race ./...; fi

README.md

@@ -1,11 +1,11 @@
 <p align="center"><a href="https://resgate.io" target="_blank" rel="noopener noreferrer"><img width="100" src="https://resgate.io/img/resgate-logo.png" alt="Resgate logo"></a></p>
 <h2 align="center"><b>RES Service for Go</b><br/>Synchronize Your Clients</h2>
 <p align="center">
-<a href="http://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
 <a href="http://goreportcard.com/report/jirenius/go-res"><img src="http://goreportcard.com/badge/github.com/jirenius/go-res" alt="Report Card"></a>
 <a href="https://travis-ci.com/jirenius/go-res"><img src="https://travis-ci.com/jirenius/go-res.svg?branch=master" alt="Build Status"></a>
 <a href="https://coveralls.io/github/jirenius/go-res?branch=master"><img src="https://coveralls.io/repos/github/jirenius/go-res/badge.svg?branch=master" alt="Coverage"></a>
-<a href="http://godoc.org/github.com/jirenius/go-res"><img src="https://godoc.org/github.com/jirenius/go-res?status.svg" alt="GoDoc"></a>
+<a href="https://pkg.go.dev/github.com/jirenius/go-res"><img src="https://img.shields.io/static/v1?label=reference&message=go.dev&color=5673ae" alt="Reference"></a>
 </p>
 
 ---
@@ -40,31 +40,42 @@ func main() {
    s.ListenAndServe("nats://localhost:4222")
 }
 ```
+> **Prerequisite**
+>
+> [Install](https://resgate.io/docs/get-started/installation/) *NATS Server* and *Resgate*. Can be done with 3 docker commands:
+> ```text
+> docker network create res
+> docker run -d --name nats -p 4222:4222 --net res nats
+> docker run --name resgate -p 8080:8080 --net res resgateio/resgate --nats nats://nats:4222
+> ```
+
 
 ## Examples
 
 | Example | Description
 | --- | ---
-| [Edit Text](examples/edit-text/) | Text field that can be edited by multiple clients concurrently.
-| [Edit Text BadgerDB](examples/edit-text-badgerdb/) | Edit Text example using BadgerDB middleware to persist all changes.
-| [Book Collection](examples/book-collection/) | List of book titles & authors that can be edited by many.
-| [Book Collection BadgerDB](examples/book-collection-badgerdb/) | Book Collection example using BadgerBD middleware to persist all changes.
+| [Hello World](examples/01-hello-world/) | Smallest of services serving a static message.
+| [Edit Text](examples/02-edit-text/) | Single text field that is updated in real time.
+| [Edit Text Persisted](examples/03-edit-text-persisted/) | Edit Text example persisting changes using BadgerDB middleware.
+| [Book Collection](examples/04-book-collection/) | List of book titles & authors that can be edited by many.
+| [Book Collection Persisted](examples/05-book-collection-persisted/) | Book Collection example persisting changes using BadgerBD middleware.
+| [Search Query](examples/06-search-query/) | Make live queries against a large customer database.
 
 > **Note**
 >
 > Above examples are complete with both service and client.
 
-## Middleware <a href="http://godoc.org/github.com/jirenius/go-res/middleware"><img src="https://godoc.org/github.com/jirenius/go-res/middleware?status.svg" alt="GoDoc"></a>
+## Middleware
 
-The `middleware` sub-package contains middleware that adds handler functions to a `res.Handler`, to perform tasks such as:
+The *middleware* subfolder contains packages that adds handler functions to a `res.Handler`, to perform tasks such as:
 
-* storing, loading and updating persisted data
+* store, load and update persisted data
 * synchronize changes between multiple service instances
-* provide helpers for complex live queries
+* perform live queries with indexed searches
 
-| Name | Description
-| --- | ---
-| `middleware.BadgerDB` | Stores and updates resources in a BadgerDB using the events.
+| Name | Description | Documentation
+| --- | --- | ---
+| [resbadger](middleware/resbadger) | BadgerDB storage middleware. | <a href="https://pkg.go.dev/github.com/jirenius/go-res/middleware/resbadger"><img src="https://img.shields.io/static/v1?label=reference&message=go.dev&color=5673ae" alt="Reference"></a>
 
 ## Usage
 

codec.go

@@ -17,6 +17,10 @@ type successResponse struct {
 	Result interface{} `json:"result"`
 }
 
+type resourceResponse struct {
+	Resource Ref `json:"resource"`
+}
+
 type errorResponse struct {
 	Error *Error `json:"error"`
 }

errors.go

@@ -27,21 +27,21 @@ func InternalError(err error) *Error {
 
 // Predefined error codes
 const (
-	CodeAccessDenied     = "system.accessDenied"
-	CodeInternalError    = "system.internalError"
-	CodeInvalidParams    = "system.invalidParams"
-	CodeMethodNotFound   = "system.methodNotFound"
-	CodeNotFound         = "system.notFound"
-	CodeTimeout          = "system.timeout"
-	CodeBadRequest       = "system.badRequest"
-	CodeMethodNotAllowed = "system.methodNotAllowed"
+	CodeAccessDenied   = "system.accessDenied"
+	CodeInternalError  = "system.internalError"
+	CodeInvalidParams  = "system.invalidParams"
+	CodeInvalidQuery   = "system.invalidQuery"
+	CodeMethodNotFound = "system.methodNotFound"
+	CodeNotFound       = "system.notFound"
+	CodeTimeout        = "system.timeout"
 )
 
 // Predefined errors
 var (
 	ErrAccessDenied   = &Error{Code: CodeAccessDenied, Message: "Access denied"}
 	ErrInternalError  = &Error{Code: CodeInternalError, Message: "Internal error"}
 	ErrInvalidParams  = &Error{Code: CodeInvalidParams, Message: "Invalid parameters"}
+	ErrInvalidQuery   = &Error{Code: CodeInvalidQuery, Message: "Invalid query"}
 	ErrMethodNotFound = &Error{Code: CodeMethodNotFound, Message: "Method not found"}
 	ErrNotFound       = &Error{Code: CodeNotFound, Message: "Not found"}
 	ErrTimeout        = &Error{Code: CodeTimeout, Message: "Request timeout"}

examples/01-hello-world/README.md

@@ -0,0 +1,52 @@
+# Hello World Example
+
+**Tags:** *Models*
+
+## Description
+Simple service serving a message to the world.
+
+## Prerequisite
+
+* [Download](https://golang.org/dl/) and install Go
+* [Install](https://resgate.io/docs/get-started/installation/) *NATS Server* and *Resgate* (done with 3 docker commands).
+
+## Install and run
+
+```text
+git clone https://github.com/jirenius/go-res
+cd go-res/examples/01-hello-world
+go run main.go
+```
+
+## Things to try out
+
+### Access API through HTTP
+* Open the browser and go to:
+    ```text
+    http://localhost:8080/api/example/model
+    ```
+
+### Access API through WebSocket
+* Open *Chrome* and go to [resgate.io - resource viewer](https://resgate.io/viewer).
+* Type in the resource ID below, and click *View*:
+    ```text
+    example.model
+    ```
+    > **Note**
+    >
+    > Chrome allows websites to connect to *localhost*, while other browsers may give a security error.
+
+### Real time update on static resource
+* Stop the project, and change the `"Hello, World!"` message in *main.go*.
+* Restart the project and observe how the message is updated in the viewer (see [above](#access-api-through-websocket)).
+
+### Get resource with ResClient
+* In the [resgate.io - resource viewer](https://resgate.io/viewer), open the DevTools console (*Ctrl+Shift+J*).
+* Type the following command, and press *Enter*:
+    ```javascript
+    client.get("example.model").then(m => console.log(m.message));
+    ```
+    > **Note**
+    >
+    > The resource viewer app stores the *ResClient* instance in the global `client` variable, for easy access.
+

examples/01-hello-world/main.go

@@ -0,0 +1,16 @@
+package main
+
+import res "github.com/jirenius/go-res"
+
+func main() {
+	s := res.NewService("example")
+	s.Handle("model",
+		res.Access(res.AccessGranted),
+		res.GetModel(func(r res.ModelRequest) {
+			r.Model(map[string]string{
+				"message": "Hello, World!",
+			})
+		}),
+	)
+	s.ListenAndServe("nats://localhost:4222")
+}

examples/edit-text/.gitignore examples/02-edit-text/.gitignore

@@ -0,0 +1,60 @@
+# Edit Text Example
+
+**Tags:** *Models*, *Call methods*, *Client subscriptions*
+
+## Description
+A simple text field that can be edited by multiple clients simultaneously.
+
+## Prerequisite
+
+* [Download](https://golang.org/dl/) and install Go
+* [Install](https://resgate.io/docs/get-started/installation/) *NATS Server* and *Resgate* (done with 3 docker commands).
+
+## Install and run
+
+```text
+git clone https://github.com/jirenius/go-res
+cd go-res/examples/02-edit-text
+go run main.go
+```
+
+Open the client
+```
+http://localhost:8082
+```
+
+## Things to try out
+
+### Realtime updates
+* Open the client in two separate tabs.
+* Edit the message in one tab, and observe realtime updates in both.
+
+### System reset
+* Stop the service.
+* Edit the default text (`"Hello, Go World!"`) in *main.go*.
+* Restart the service to observe resetting of the message in all clients.
+
+## API
+
+Request | Resource | Description
+--- | --- | ---
+*get* | `text.shared` | Simple model.
+*call* | `text.shared.set` | Sets the model's *message* property.
+
+## REST API
+
+Resources can be retrieved using ordinary HTTP GET requests, and methods can be called using HTTP POST requests.
+
+### Get model
+```
+GET http://localhost:8080/api/text/shared
+```
+
+### Update model
+```
+POST http://localhost:8080/api/text/shared/set
+```
+*Body*  
+```
+{ "message": "Updated through HTTP" }
+```

examples/02-edit-text/README.md

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<title>Edit Text Example</title>
+		<link rel="icon" href="data:,">
+		<script src="https://cdn.jsdelivr.net/npm/resclient@latest/dist/resclient.min.js"></script>
+	</head>
+	<body>
+		<p>Try running the client in two separate tabs!</p>
+		<p>Web resource: <a href="http://localhost:8080/api/text/shared" target="_blank">http://localhost:8080/api/text/shared</a></p>
+		<hr />
+		<div id="root"><input id="input" /></div>
+		<script>
+			const ResClient = resclient.default;
+
+			// Creating the client instance.
+			let client = new ResClient('ws://localhost:8080');
+
+			// Get the model from the service.
+			client.get('text.shared').then(model => {
+				// Set value of the input element
+				input.value = model.message;
+
+				// Listen for user input and call set to update the remote model.
+				input.addEventListener('input', () => {
+					model.set({ message: input.value });
+				});
+
+				// Listen for model change events.
+				// The model will be unsubscribed after calling model.off
+				model.on('change', () => {
+					input.value = model.message;
+				});
+			}).catch(err => {
+				root.textContent = err.code == 'system.connectionError'
+					? "Connection error. Are NATS Server and Resgate running?"
+					: err.message;
+			});
+		</script>
+	</body>
+</html>

examples/02-edit-text/index.html

@@ -1,6 +1,6 @@
 /*
 This is an example of a simple text field that can be edited by multiple clients.
-* It exposes a single resource: "example.shared".
+* It exposes a single resource: "text.shared".
 * It allows setting the resource's Message property through the "set" method.
 * It resets the model on server restart.
 * It serves a web client at http://localhost:8082
@@ -24,9 +24,9 @@ var shared = &Model{Message: "Hello, Go World!"}
 
 func main() {
 	// Create a new RES Service
-	s := res.NewService("example")
+	s := res.NewService("text")
 
-	// Add handlers for "example.shared" resource
+	// Add handlers for "text.shared" resource
 	s.Handle("shared",
 		// Allow everone to access this resource
 		res.Access(res.AccessGranted),

examples/edit-text/main.go examples/02-edit-text/main.go

@@ -0,0 +1,54 @@
+# Edit Text Persisted Example
+
+**Tags:** *Models*, *Call methods*, *Client subscriptions*, *Persistence*
+
+## Description
+This is the Edit Text example where all changes are persisted using the BadgerDB middleware. With a database middleware, both clients and database can be updated with a single event.
+
+## Prerequisite
+
+* [Download](https://golang.org/dl/) and install Go
+* [Install](https://resgate.io/docs/get-started/installation/) *NATS Server* and *Resgate* (done with 3 docker commands).
+
+## Install and run
+
+```text
+git clone https://github.com/jirenius/go-res
+cd go-res/examples/03-edit-text-persisted
+go run main.go
+```
+
+Open the client
+```
+http://localhost:8083
+```
+
+## Things to try out
+
+### BadgerDB persistence
+Run the client and make edits to the text. Restart the service and observe all changes are persisted.
+
+## API
+
+Request | Resource | Description
+--- | --- | ---
+*get* | `text.shared` | Simple model.
+*call* | `text.shared.set` | Sets the model's *message* property.
+
+## REST API
+
+Resources can be retrieved using ordinary HTTP GET requests, and methods can be called using HTTP POST requests.
+
+### Get model
+```
+GET http://localhost:8080/api/text/shared
+```
+
+### Update model
+```
+POST http://localhost:8080/api/text/shared/set
+```
+*Body*  
+```
+{ "message": "Updated through HTTP" }
+```