@push-rpc/next 2.0.10 → 2.0.12

package/README.md

@@ -1,4 +1,211 @@
-Client/server framework
+A TypeScript framework for organizing bidirectional typesafe client-server communication. Supports
+server-initiated data push (subscriptions). Uses HTTP, JSON and, optionally, WebSockets.
+Main focus is on simplicity and good developer experience.
+
+Best used with monorepos using TypeScript. Can also be used with JavaScript and non-JS clients.
+
+## Features
+
+- Developer friendly - remote call is a plain TS call for easy tracing between client and server and good
+  IDE integration.
+- Based on HTTP, easy to integrate with existing infrastructure. Call visibility in browser DevTools.
+- Gradually upgradeable - WS is only used when you need subscriptions.
+- Server runs on Node.JS, client runs in the Node.JS/Browser/ReactNative.
+
+Extra:
+
+- Client & Server middlewares.
+- Consume compressed HTTP requests.
+- Send & receive plain-text data.
+- Throttling for subscriptions.
+- Broken WS connection detection & auto-reconnecting.
+
+## History note!
+
+Initially this project supported WS-only communication akin to OCPP-J protocol for EV charging stations.
+Since that, library for OCPP-J was extracted to a separate project and this project was reworked to focus on generic
+client/server communication.
+
+## Getting Started
+
+```
+npm install @push-rpc/next
+```
+
+For implementing subscriptions at backend, you'll also need to install ws package:
+
+```
+npm install ws
+```
+
+Contract between server and client is defined in shared module.
+
+api.ts:
+
+```
+// Note that API definition is plain TypeScript and is independent of the library
+
+export type Services = {
+  todo: TodoService
+}
+
+export type TodoService = {
+  addTodo(req: {text: string}, ctx?: any): Promise<void>
+  getTodos(ctx?: any): Promise<Todo[]>
+}
+
+export type Todo = {
+  id: string
+  text: string
+  status: "open" | "closed"
+}
+
+```
+
+Contact then used in client.ts:
+
+```
+import {Services} from "./api"
+import {consumeServices} from "@push-rpc/next"
+
+async function startClient() {
+  const {remote} = await consumeServices<Services>("http://127.0.0.1:8080/rpc")
+
+  console.log("Client created")
+
+  await remote.todo.getTodos.subscribe((todos) => {
+    console.log("Got todo items", todos)
+  })
+
+  await remote.todo.addTodo({text: "Buy groceries"})
+}
+
+startClient()
+
+```
+
+And implemented in server.ts:
+
+```
+import {Todo, TodoService} from "./api"
+import {publishServices} from "@push-rpc/next"
+
+async function startServer() {
+  const storage: Todo[] = []
+
+  class TodoServiceImpl implements TodoService {
+    async addTodo({text}: {text: string}) {
+      storage.push({
+        id: "" + Math.random(),
+        text,
+        status: "open",
+      })
+
+      console.log("New todo item added")
+      services.todo.getTodos.trigger()
+    }
+
+    async getTodos() {
+      return storage
+    }
+  }
+
+  const {services} = await publishServices(
+    {
+      todo: new TodoServiceImpl(),
+    },
+    {
+      port: 8080,
+      path: "/rpc",
+    }
+  )
+
+  console.log("RPC Server started at http://localhost:8080/rpc")
+}
+
+startServer()
+```
+
+Run server.ts and then client.ts.
+
+Server will send empty todo list on client connecting and then will send updated list on adding new item.
+
+## Protocol Details
+
+There are the types of messages that can be sent from client to server:
+
+1. **Call** - a request to synchronously execute a remote function. Implemented as HTTP POST request. URL contains the
+   remote function name. Body contains JSON-encoded list of arguments. Response is JSON-encoded result of the
+   function.
+
+   ```
+   POST /rpc/todo/addTodo HTTP/1.1
+   Content-Type: application/json
+   X-Rpc-Client-Id: GoQ_xVYcthSEqMxDGV212
+    
+   [{"text": "Buy groceries"}]
+   
+   ...
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+   {"id": "123"}
+    ```
+
+   `X-Rpc-Client-Id` header is used to identify caller clients. In can be used for session tracking. Client ID is
+   available at server side in the context.
+
+2. **Subscribe** - a request to subscribe to a remote function updates. Implemented as HTTP PUT request. URL contains
+   the remote function name. Body contains JSON-encoded list of arguments. Response is JSON-encoded result of the
+   function.
+
+   ```
+   PUT /rpc/todo/getTodos HTTP/1.1
+   Content-Type: application/json
+    
+   []
+   
+   ...
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+   [{"id": 1, text: "Buy groceries", status: "open"}]
+   ```
+
+   Before subscribing, client would establish a WebSocket connection to the server. Server would then use established
+   connection to send subscription updates. Client ID is used to link WebSocket connection and HTTP requests.
+
+3. **Unsubscribe** - a request to unsubscribe from a remote function updates. Implemented as HTTP PATCH request. URL
+   contains the remote function name. Body contains JSON-encoded list of arguments. Response is always empty.
+
+   ```
+   PATCH /rpc/todo/getTodos HTTP/1.1
+   Content-Type: application/json
+    
+   []
+   
+   ...
+   HTTP/1.1 204 No Content
+   ```
+
+Server sends updates to subscribed clients using WebSocket connection. Clients establish WebSocket connection using
+the base URL:
+
+```
+GET /rpc HTTP/1.1
+Connection: Upgrade
+Upgrade: websocket
+Sec-Websocket-Protocol: GoQ_xVYcthSEqMxDGV212
+```
+
+`Sec-Websocket-Protocol` header is used to transfer client ID.
+
+After successful subscription, server sends updates to the client. Each update is a JSON-encoded message containing
+topic name, remote function result and subscription parameters if any:
+
+```
+["todo/getTodos", [{"id": 1, text: "Buy groceries", status: "open"}], ...]
+```
+
+Both client & server will try to connect broken connections by sending WS ping/pongs.
 
 ## Glossary
 
@@ -19,30 +226,17 @@ subscribe' invocation and copied to each 'trigger' invocation. Context, created
 contain only JSON data, to allow copying. Context can be modified in middlewares; these modification doesn't have to be
 JSON-only.
 
-**Middlewares**. Middlewares are used to intercept client and server requests. Both calls and subscriptions can be
-intercepted?. Middlewares can be attached on both client and server side. Middlewares receive context as the last
-arguments in the invocation. Middleware can modify context.
+**Middlewares**. Middlewares are used to intercept client requests, server requests implementations and client
+notifications. Both calls and subscriptions can be intercepted. Middlewares can be attached on both client and server
+side. Middleware can modify context and parameters and data.
+
+Request middleware is called with parameters (ctx, next, ...parameters)
+Client notifications middleware is called with parameters (ctx, next, data, parameters).
 
 **Throttling**. Used to limit number of notifications from the remote functions. With throttling enabled, not all
 triggers will result in new notifications. Throttling can be used with reducers to aggregate values supplied in
 triggers.
 
-## Issues / TBDs
-
-- [important] Importing index.js from the root of the package will import node's http package. Not good for clients.
-- Browser sockets don't have 'ping' event. Need to find a different way to detect connection loss.
-- Перевірити, що throttling працює відразу для всіх підписників
-
-## Features
+# Limitations
 
-- Developer friendly - everything is plain TypeScript calls, easy call tracing between client and server, good
-  integration with IDE & Browser DevTools
-- Based on HTTP, easy to integrate with existing infrastructure
-- Gradually upgradeable - WS is only used when you need subscriptions
-- Supports compressed HTTP requests.
-- Server runs on Node.JS, client runs in the Node.JS/Browser/ReactNative. For RN some extra setup is required (
-  document). Bun/Deno should also work, but not officially supported.
-- Limited cookie support. Due to limited support in React Native, Cookies can be set and read during HTTP requests and
-  set during WS connection establishment. So if you need to share cookies between HTTP and WS, you need to make call (
-  HTTP POST) right after creating client, and establish WS connection (ie make subscribe, HTTP PUT) only after that.
-  Cookies cannot be shared when `connectOnCreate` client option is true.
+- Cookies are not been sent during HTTP & WS requests.

package/example/client.ts

@@ -8,7 +8,7 @@ async function startClient() {
 
   await remote.todo.getTodos.subscribe((todos) => {
     console.log("Got todo items", todos)
-  }, null)
+  })
 
   await remote.todo.addTodo({text: "Buy groceries"})
 }

package/example/server.ts

@@ -1,9 +1,9 @@
 import {Todo, TodoService} from "./api"
 import {publishServices} from "../src/server/index"
 
-const storage: Todo[] = []
-
 async function startServer() {
+  const storage: Todo[] = []
+
   class TodoServiceImpl implements TodoService {
     async addTodo({text}: {text: string}) {
       storage.push({