lakutata 3.1.4 → 3.1.6

package/doc/en/ServiceCalls.md

@@ -2,10 +2,10 @@
 
 A service action (`@ServiceAction`) is called with a message rather than a URL: an object whose keys select the action,
 its **pattern**, and whose other keys are the input. The same actions can be served over several transports at once:
-plain HTTP, Socket.IO, JSON-RPC 2.0 (over HTTP, WebSocket or the standard input and output) and the IPC of Electron, as
-this guide describes, and gRPC, NATS and the data channels of WebRTC, which have their own guides. The controllers and
-their actions are described in [Controllers](Controllers.md), the entrypoint and its adapters in
-[Entrypoint](Entrypoint.md).
+plain HTTP, Socket.IO, JSON-RPC 2.0 (over HTTP, WebSocket or the standard input and output), the IPC of Electron, the
+windows of NW.js and the user interface of a mobile application of React Native, as this guide describes, and gRPC, NATS
+and the data channels of WebRTC, which have their own guides. The controllers and their actions are described in
+[Controllers](Controllers.md), the entrypoint and its adapters in [Entrypoint](Entrypoint.md).
 
 ## 1. A first service
 
@@ -136,7 +136,8 @@ class OrderController extends Controller {
 
 ## 3. The response
 
-The HTTP service, Socket.IO and Electron answer with an envelope; JSON-RPC answers with its own responses (section 4).
+The HTTP service, Socket.IO, Electron, NW.js and React Native answer with an envelope; JSON-RPC answers with its own
+responses (section 4).
 
 ```text
 {"success": true, "error": null, "payload": <the result>}
@@ -179,6 +180,8 @@ export async function call<T>(message: Record<string, unknown>): Promise<T> {
 | `socketIOServiceEntrypoint()` | `lakutata/adapter/socket.io` | `socket.io` (`socket.io-client` on the clients) | An emit with an acknowledgement | Socket.IO events |
 | `jsonRPCServiceEntrypoint()` | `lakutata/adapter/jsonrpc` | `ws`, for WebSocket | A JSON-RPC 2.0 request | Notifications (WebSocket, stdio) |
 | `electronIPCServiceEntrypoint()` | `lakutata/adapter/electron` | (Electron) | `ipcRenderer.invoke()` | IPC messages |
+| `nwjsServiceEntrypoint()` | `lakutata/adapter/nwjs` | (NW.js) | A call of its bridge, by the host page of a window | Calls of the function the host page gives |
+| `reactNativeServiceEntrypoint()` | `lakutata/adapter/react-native` | | A line of JSON from the host | Lines of JSON |
 | `grpcServiceEntrypoint()` | `@lakutata/grpc/service` | `@lakutata/grpc` | See [GRPC](GRPC.md) | gRPC streams |
 | `natsServiceEntrypoint()` | `@lakutata/nats` | `@lakutata/nats` | See [NATS](NATS.md) | NATS messages |
 | `webrtcServiceEntrypoint()` | `@lakutata/webrtc` | `@lakutata/webrtc` | A JSON-RPC 2.0 request on a data channel, see [WebRTC](WebRTC.md) | Notifications |
@@ -468,6 +471,79 @@ contextBridge.exposeInMainWorld('service', {
 - The Electron templates of `lakutata create` contain a preload script of this shape, and a `window.ipc` for the pages,
   whose `invoke()` returns the payload or throws the error.
 
+### NW.js
+
+`nwjsServiceEntrypoint()` serves the actions to the windows of an NW.js application, in its background script (its
+Node.js context). NW.js gives Node.js to the pages of its windows, and an iframe of such a page does not keep Node.js
+from its content (its sandbox is ignored): the user interface runs in a `<webview>`, without Node.js, held by a trusted
+page of the window (its host page). The adapter puts a bridge on the global object that NW.js shares with its windows,
+`global[Symbol.for(key)]`; the host page forwards the requests of the interface to it, and gives it the function that
+pushes the events to the interface.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `key` | `'lakutata:service'` (`NWJS_SERVICE_BRIDGE`) | The key of the bridge on the global object |
+| `global` | the global object of NW.js | The object the bridge is put on, or a stand-in in the tests |
+
+| Method of the bridge | Meaning |
+|---|---|
+| `invoke(message, clientId)` | Invokes an action: resolves to the envelope, never rejects |
+| `subscribe(clientId, push)` | Makes a page a client: the events pushed to it are given to `push(event, args)` |
+| `unsubscribe(clientId)` | Removes a client, when its page is loaded again or its window closed: its requests in progress are aborted |
+
+The host page forwards the messages of the interface, from the page loaded in its `<webview>` only:
+
+```javascript
+const view = document.querySelector('webview')
+const origin = new URL(view.src).origin
+const bridge = global[Symbol.for('lakutata:service')]
+const send = (message) => view.contentWindow.postMessage(message, origin)
+window.addEventListener('message', async (event) => {
+    if (event.source !== view.contentWindow || event.origin !== origin) return
+    const {type, id, message, clientId} = event.data
+    if (type === 'invoke') send({type: 'response', id: id, response: await bridge.invoke(message, clientId)})
+    if (type === 'subscribe') bridge.subscribe(clientId, (name, args) => send({type: 'event', name: name, args: args}))
+})
+```
+
+- The `<webview>` loads the files of the application when its partition is declared in the manifest of NW.js:
+  `"webview": {"partitions": [{"name": "trusted", "accessible_resources": ["<all_urls>"]}]}` (the builder writes it).
+- A page loaded again in the `<webview>` is a new client: the host page unsubscribes the previous one.
+- The NW.js templates of `lakutata create` contain such a host page (`packages/app/host`), and a `window.ipc` for the
+  interface like the one of the Electron templates.
+
+### React Native
+
+`reactNativeServiceEntrypoint()` serves the actions to the user interface of a mobile application of React Native
+(Android, iOS, HarmonyOS), in the Node.js that the application embeds. The native module of the application starts
+Node.js and gives it one end of a socket, whose file descriptor is in the environment variable `LAKUTATA_NODE_FD`. The
+adapter reads the messages of the host on that socket and writes its responses and events there, one JSON object per
+line. The values arrive as JSON carries them: a `Date` arrives as its string, a `Buffer` as `{type, data}`, `undefined`
+is left out, and a result that JSON cannot hold (a `bigint`, a cycle) is answered with an error.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `socket` | a socket on the file descriptor in `LAKUTATA_NODE_FD` | The connection to the host, or a stand-in in the tests |
+| `pause` | | Called when the application goes to the background, before the host is told that the application is ready for it |
+| `resume` | | Called when the application comes back from the background |
+
+| The host writes | The adapter answers |
+|---|---|
+| `{"type":"invoke","id":1,"clientId":"ui","data":{"cmd":"greet","name":"you"}}` | `{"type":"response","id":1,"response":{"success":true,"error":null,"payload":…}}` |
+| `{"type":"subscribe","clientId":"ui"}` | `{"type":"subscribed","clientId":"ui"}`, then the events pushed to the client |
+| `{"type":"unsubscribe","clientId":"ui"}` | Nothing; the requests of the client in progress are aborted |
+| `{"type":"pause"}` | `{"type":"paused"}`, once the `pause` option has run |
+| `{"type":"resume"}` | Nothing; the `resume` option runs |
+
+- The lines that the host writes before the application listens wait in the socket: none is lost. The answer to the
+  subscription tells the interface that the application is ready.
+- On iOS, the host asks the system for time to finish before the application is suspended, sends `pause`, and lets the
+  application be suspended once `paused` comes (or when the time runs out).
+- When Node.js ends (`process.exit()`, an uncaught exception), the mobile application keeps running: the native module
+  reports the exit code and can start Node.js again.
+- The `mobile-react` template of `lakutata create` contains such a native module, and an `ipc` for the interface like
+  the one of the Electron templates, both in its package `packages/ipc`.
+
 ## 5. Clients and events
 
 The transports that keep their clients connected can push events to them. A client is identified by the id it gives:
@@ -480,6 +556,8 @@ The transports that keep their clients connected can push events to them. A clie
 | JSON-RPC over WebSocket | The `id` header or `id` query parameter of the connection, else a random id |
 | JSON-RPC over stdio | `'stdio'` |
 | Electron | The id the page gives when it subscribes or invokes |
+| NW.js | The id the host page gives to the bridge for its page |
+| React Native | The id the user interface gives when it subscribes or invokes |
 | WebRTC | The member id of the caller in its room |
 
 An action reads the id of its client in `this.context.clientId`. The `entrypoint` component pushes the events:
@@ -515,6 +593,8 @@ A client receives `notify(clientId, 'progress', 50, 'half')` as:
 | Socket.IO | `socket.on('progress', (percent, label) => …)` |
 | JSON-RPC (WebSocket, stdio) | `{"jsonrpc": "2.0", "method": "progress", "params": [50, "half"]}` |
 | Electron | `('progress', [50, 'half'])`, through the `subscribe` of the preload script above |
+| NW.js | `('progress', [50, 'half'])`, given to the function of the `subscribe` of the bridge |
+| React Native | The line `{"type":"event","clientId":…,"event":"progress","args":[50,"half"]}`, which the host passes to the interface |
 | WebRTC | `proxy.on('progress', (percent, label) => …)` of a `PeerServiceProxy` |
 
 ## 6. Stopping and leaving

package/doc/en/UpgradingFrom1.md

@@ -20,7 +20,7 @@ packages obtained elsewhere may have APIs that this page does not cover.
 | Modules | CommonJS: imports without extensions, `__dirname` | ES modules: relative imports ending in `.js` |
 | Service actions | `@Controller({_ctrl: …})` and `@PATTERN({_act: …})` from `@lakutata-module/service` | `@ServiceAction({…})` from `lakutata/decorator/ctrl` |
 | Validation | `Validator` schemas (yup) given to `@Accept` | DTO classes with `@Expect` |
-| Node.js | `>=14.15.1` (`@lakutata/core` 1.0.60) | `^22.13.0 \|\| >=24.11.0` |
+| Node.js | `>=14.15.1` (`@lakutata/core` 1.0.60) | `>=18.10.0` |
 
 **`@lakutata/core` 3 is not a new version of the 1.x library.** It is the core of Lakutata 3, a different API under the
 same name. `npm install @lakutata/core@latest`, or a range such as `*`, in a 1.x project puts it in place of the 1.x
@@ -392,7 +392,7 @@ are built differently, so the entries that 1.x wrote are not found: start with a
 - **The `lakutata` field of `package.json`** told the 1.x tool the kind of the project (`type`), its directories and
   its configuration file. In 3.x the field has another meaning (the `resources` and the `installer` of a packed
   application, [Packaging](Packaging.md)): remove the 1.x one.
-- **Node.js, TypeScript and modules.** Node.js `^22.13.0 || >=24.11.0`, TypeScript 6 as in the templates, ES modules
+- **Node.js, TypeScript and modules.** Node.js `>=18.10.0`, TypeScript 6 as in the templates, ES modules
   (`"type": "module"`, relative imports ending in `.js`), `tsconfig.json` extending `lakutata/tsconfig.json`.
 - **Ports.** The service module listened on a port of its own (6912 by default) and the registry on another (6911).
   The 3.x adapters listen on the ports of their options, and a service on NATS only connects out to the NATS server:

package/doc/en/UpgradingFrom2.md

@@ -17,15 +17,15 @@ It is for the projects that depend on the package `lakutata` at version 2. A pro
 | Exported functions | PascalCase: `BuildEntrypoints`, `BuildDatabaseOptions`, `MD5` | camelCase: `buildEntrypoints`, `buildDatabaseOptions`, `md5` |
 | Transports | Written by hand: `BuildHTTPEntrypoint((module, routeMap, handler, registerDestroy) => …)` | Adapters: `expressHTTPEntrypoint()` from `lakutata/adapter/express`… |
 | Subpaths of 3.x only | | `lakutata/utils`, `lakutata/security`, `lakutata/adapter/*`, `lakutata/com/{containerd,mutex,queue,i18n}` |
-| Node.js | `>=20` | `^22.13.0 \|\| >=24.11.0` |
+| Node.js | `>=20` | `>=18.10.0` |
 
 `npx @lakutata/cli info` prints the versions of the tool, of the framework and of Node.js, and the `lakutata` version
 that the project declares and the one installed. There is no upgrade command: the steps below are done by hand.
 
 ## 2. The steps
 
-- **Node.js** `^22.13.0 || >=24.11.0` (22.13 or a later 22.x, or 24.11 and later; not 23). Update `engines`, the CI
-  matrix and the base images of the Dockerfiles.
+- **Node.js** `>=18.10.0` (3.0 to 3.1 needed `^22.13.0 || >=24.11.0`). The versions 2.x needs (`>=20`) are among them:
+  `engines`, the CI matrix and the Dockerfiles can stay.
 - **A TypeScript that knows `"module": "Node20"`** (the templates use TypeScript 6): `lakutata/tsconfig.json` now sets
   it (2.x: `Node16`), and older compilers reject it.
 - **`package.json`**: `"type": "module"`, `lakutata` `^3.0.0`, the `@lakutata/*` packages at `^3.0.0` too, and
@@ -281,7 +281,7 @@ Application
 ## 6. Checking the upgrade
 
 ```bash
-node --version                      # ^22.13.0 || >=24.11.0
+node --version                      # >=18.10.0
 npm ls lakutata @lakutata/core      # one version of each
 npm run build                       # tsc without errors: no 2.x import left
 grep -rnE "process\.on\('SIG|\|\| ''|(startup|launched|beforeDestroy|acceptsOption)\(|AccessDenyException|=== 500" src

package/doc/en/WebRTC.md

@@ -224,10 +224,10 @@ export class Telemetry extends Component {
 ```
 
 An `http:` or `https:` URL uses Socket.IO (install `socket.io-client`), a `ws:` or `wss:` URL uses JSON-RPC over the
-`WebSocket` of Node.js 22 and Bun. Its options: `url`, `id` (a random UUID by default), `path` (of Socket.IO), `auth`
-(more fields of the Socket.IO handshake, a token), `timeout`, and the options of its connections (`iceTransportPolicy`,
-`icePortRange`, `iceAdditionalHostAddresses`, `codecs`, `threads`). It is `@Transient`: each `getObject()` gives a new
-client, and `close()` leaves its rooms and disconnects.
+global `WebSocket` of Node.js 22 and Bun, else over the `WebSocket` of the package `ws` (install `ws`). Its options: `url`, `id`
+(a random UUID by default), `path` (of Socket.IO), `auth` (more fields of the Socket.IO handshake, a token), `timeout`,
+and the options of its connections (`iceTransportPolicy`, `icePortRange`, `iceAdditionalHostAddresses`, `codecs`,
+`threads`). It is `@Transient`: each `getObject()` gives a new client, and `close()` leaves its rooms and disconnects.
 
 ### Calling the actions of an application