update docs for new version

README-zh.md

@@ -169,7 +169,7 @@ end[] <- [['YPO]]
 Cozo 可以安装在一大堆不同的语言与环境中：
 
 | 语言/环境                                                                                                 | 官方支持的平台                                                                                              | 存储引擎  |
-|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------|
+|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------|
 | [Python](https://github.com/cozodb/pycozo)（[国内镜像](https://gitee.com/cozodb/pycozo)）                   | Linux (x86_64), Mac (ARM64, x86_64), Windows (x86_64)                                                | MQR   |
 | [NodeJS](./cozo-lib-nodejs)                                                                           | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                         | MQR   |
 | [浏览器](./cozo-lib-wasm)                                                                                | 支持[WASM](https://developer.mozilla.org/en-US/docs/WebAssembly#browser_compatibility)的浏览器（较新的浏览器全都支持） | M     |
@@ -180,7 +180,7 @@ Cozo 可以安装在一大堆不同的语言与环境中：
 | [Rust](https://docs.rs/cozo/)                                                                         | 任何支持`std`的[平台](https://doc.rust-lang.org/nightly/rustc/platform-support.html)（源代码编译）                 | MQRST |
 | [Go](https://github.com/cozodb/cozo-lib-go)（[国内镜像](https://gitee.com/cozodb/cozo-lib-go)）             | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                         | MQR   |
 | [C/C++/支持 C FFI 的语言](./cozo-lib-c)                                                                    | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                         | MQR   |
-| [独立的 HTTP 服务](./cozoserver)                                                                         | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                         | MQRST |
+| [独立的 HTTP 服务](./cozo-bin)                                                                             | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                         | MQRST |
 
 “存储引擎”列中各个字母的含义：
 
@@ -199,7 +199,7 @@ Cozo 的 [Rust API 文档](https://docs.rs/cozo/)（英文）中有一些额外
 RocksDB 有五花八门的选项以供用户进行性能调优。但是调优这个问题太复杂了，就连 RocksDB 他们自己也搞不定，所以实际生产中他们用的是强化学习来自动调优。对于 95% 的用户来说，费这个劲根本不值得，尤其是 Cozo “开箱”的设置就已经相当快、足够快了。
 
 如果你坚信你是剩下那 5% 里面的：当你用 RocksDB 引擎创建 CozoDB 实例时，你提供过一个存储数据的目录路径。如果在这个目录里创建一个名为`options`的文件，RocksDB 引擎便会将其解读为 [RocksDB 选项文件](https://github.com/facebook/rocksdb/wiki/RocksDB-Options-File)
-并应用其中的设置。如果使用的是独立的 `cozoserver` 程序，激活此功能时会有一条提示日志。
+并应用其中的设置。如果使用的是独立的 `cozo` 程序，激活此功能时会有一条提示日志。
 
 每次 RocksDB 引擎启动时，存储目录下的 `data/OPTIONS-XXXXXX` 文件会记录当前应用设置。你可以把这个文件拷贝出来，在其基础上修改。如果你不是 RocksDB 的专家，建议只改动那些你大概知道什么意思的数字型选项。设置不当可能会搞乱、搞坏数据库。
 
@@ -247,7 +247,7 @@ Cozo 的 [Rust API](https://docs.rs/cozo/) 实际上就是查询引擎的公共
 
 ### 语言、环境封装
 
-Cozo 的 Rust 以外的所有语言、环境都只是对 Rust API 的进一步封装。例如，在独立服务器（cozoserver）中，Rust API 被封装为了 HTTP 端点，而在 Cozo-Node 中，同步的Rust API 被封装为基于 JavaScript 运行时的异步 API。
+Cozo 的 Rust 以外的所有语言、环境都只是对 Rust API 的进一步封装。例如，在独立服务器（cozo）中，Rust API 被封装为了 HTTP 端点，而在 Cozo-Node 中，同步的Rust API 被封装为基于 JavaScript 运行时的异步 API。
 
 封装 Rust API 不难，如果你想让 Cozo 在其它语言上跑起来可以试试。Rust 有一些现成的库用来与其它语言交互。如果你想用某个语言而没有现成的交互库，我们建议你直接封装 Cozo 的 C 语言 API。官方支持的 Go 库就是这么实现的（通过 cgo）。
 

README.md

@@ -229,7 +229,7 @@ Follow the links in the table below:
 | [Rust](https://docs.rs/cozo/)                         | Source only, usable on any [platform](https://doc.rust-lang.org/nightly/rustc/platform-support.html) with `std` support | MQRST   |
 | [Golang](https://github.com/cozodb/cozo-lib-go)       | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                                            | MQR     |
 | [C/C++/language with C FFI](./cozo-lib-c)             | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                                            | MQR     |
-| [Standalone HTTP server](./cozoserver)                | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                                            | MQRST   |
+| [Standalone HTTP server](./cozo-bin)                  | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64)                                                            | MQRST   |
 
 For the storage column:
 
@@ -255,7 +255,7 @@ When you create the CozoDB instance with the RocksDB backend option, you are ask
 provide a path to a directory to store the data (will be created if it does not exist).
 If you put a file named `options` inside this directory, the engine will expect this
 to be a [RocksDB options file](https://github.com/facebook/rocksdb/wiki/RocksDB-Options-File)
-and use it. If you are using `cozoserver`, you will get a log message if
+and use it. If you are using the standalone `cozo` executable, you will get a log message if
 this feature is activated.
 
 Note that improperly set options can make your database misbehave!

cozo-bin/README-zh.md

@@ -6,23 +6,23 @@
 
 ## 下载
 
-独立服务的程序可以从 [GitHub 发布页](https://github.com/cozodb/cozo/releases) 或 [Gitee 发布页](https://gitee.com/cozodb/cozo/releases) 下载，其中名为 `cozoserver-*` 的是独立服务程序，名为 `cozoserver_all-*` 的独立程序同时支持更多地存储引擎，比如 [TiKV](https://tikv.org/)。
+独立服务的程序可以从 [GitHub 发布页](https://github.com/cozodb/cozo/releases) 或 [Gitee 发布页](https://gitee.com/cozodb/cozo/releases) 下载，其中名为 `cozo-*` 的是独立服务程序，名为 `cozo_all-*` 的独立程序同时支持更多地存储引擎，比如 [TiKV](https://tikv.org/)。
 
 ## 启动服务程序
 
 在终端中执行：
 
 ```bash
-./cozoserver
+./cozo server
 ```
 
-如此执行命令会使用纯内存的非持久化存储引擎。执行 `./cozoserver -h` 可查看如何启用其它引擎，以及其它参数。
+如此执行命令会使用纯内存的非持久化存储引擎。执行 `./cozo server -h` 可查看如何启用其它引擎，以及其它参数。
 
 若要终止程序，按下 `CTRL-C` 按键，或向进程发送 `SIGTERM` （比如通过 `kill` 命令）。
 
 ## 命令行界面
 
-在执行时加入 `-r` 或 `--repl` 参数可开启命令行界面（REPL），同时不会启动 web 服务。其它选择存储引擎的参数可一同使用。
+`./cozo repl` 可开启命令行界面（REPL），同时不会启动 web 服务。其它选择存储引擎的参数可一同使用。
 
 在界面中可以使用以下特殊命令：
 
@@ -50,7 +50,9 @@ HTTP API 返回的结果永远是 JSON 格式的。如果请求成功，则返
 
 > Cozo 的设计，基于其在一个受信任的环境中运行，且其所有用户也是由受信任的这种假设。因此 Cozo 没有内置认证与复杂的安全机制。如果你需要远程访问 Cozo 服务，你必须自己设置防火墙、加密和代理等，用来保护服务器上资源的安全。
 > 
-> 由于总是会有用户不小心将服务接口暴露于外网，Cozo 有一个补救措施：如果从非回传地址访问 Cozo，则必须在所有请求中以 HTTP 文件头 `x-cozo-auth` 的形式附上访问令牌。访问令牌的内容在启动服务的终端中有提示。注意这仅仅是一个补救措施，并不是特别可靠的安全机制，是为了尽量防止一些不由于小心而造成严重后果的悲剧。
+> 由于总是会有用户不小心将服务接口暴露于外网，Cozo 有一个补救措施：如果允许了非回传地址访问 Cozo，则必须在所有请求中以 HTTP 文件头 `x-cozo-auth` 的形式附上访问令牌。访问令牌的内容在启动服务的终端中有提示。注意这仅仅是一个补救措施，并不是特别可靠的安全机制，是为了尽量防止一些不由于小心而造成严重后果的悲剧。
+> 
+> 在有些客户端里，部分 API 加入 HTTP 文件头可能会比较困难或者根本不可能。这时也可以在查询参数 `auth` 中传入令牌。
 
 ## 所有 API
 
@@ -64,10 +66,19 @@ HTTP API 返回的结果永远是 JSON 格式的。如果请求成功，则返
 > 注意 `import` 与 `import-from-backup` 接口不会激活任何触发器。
 
 
+以下为试验性的 API：
+
+* `GET(SSE) /changes/{relation: String}` 获取某个存储表的更新，基于 [SSE](https://developer.mozilla.org/zh-CN/docs/Web/API/Server-sent_events/Using_server-sent_events).
+* `GET(SSE) /rules/{name: String}` 注册一个自定义的固定规则。查询参数 `arity` 是必须的。
+* `POST /rule-result/{id}` 将固定规则的计算结果回传给服务器，配合上一个 API 使用。
+* `POST /transact` 开始一个多语句的事务。返回的 ID 在下面几个 API 中使用。如果要进行写操作，则需要传入 `write=true` 查询参数。
+* `POST /transact/{id}` 在多语句事务中进行查询。要求的正文与 `/text-query` 所要求的相同。
+* `PUT /transact/{id}` 提交或放弃多语句事务。要求的正文是 JSON `{"abort": <bool>}`，传入真值则放弃，否则提交。如果不执行此查询则服务器会浪费系统资源。
+
 ## 编译
 
-编译 `cozoserver` 需要 [Rust 工具链](https://rustup.rs)。运行
+编译 `cozo` 需要 [Rust 工具链](https://rustup.rs)。运行
 
 ```bash
-cargo build --release -p cozoserver -F compact -F storage-rocksdb
+cargo build --release -p cozo-bin -F compact -F storage-rocksdb
 ```

cozo-bin/README.md

@@ -8,28 +8,27 @@ To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org
 ## Download
 
 The standalone executable for Cozo can be downloaded from the [release page](https://github.com/cozodb/cozo/releases).
-Look for those with names `cozoserver-*`.
-Those with names `cozoserver_all-*` supports additional storage backends
+Look for those with names `cozo-*`.
+Those with names `cozo_all-*` supports additional storage backends
 such as [TiKV](https://tikv.org/) storage, but are larger.
 
 ## Starting the server
 
-Run the cozoserver command in a terminal:
+Run the cozo command in a terminal:
 
 ```bash
-./cozoserver
+./cozo server
 ```
 
 This starts an in-memory, non-persistent database.
 For more options such as how to run a persistent database with other storage engines,
-see `./cozoserver -h`
+see `./cozo server -h`
 
 To stop Cozo, press `CTRL-C`, or send `SIGTERM` to the process with e.g. `kill`.
 
 ## The REPL
 
-If you start the server with the `-r` or `--repl` option, a web server will not be started.
-Instead, a terminal-based REPL is presented to you. The engine options can be used when
+Run `./cozo repl` to enter a terminal-based REPL. The engine options can be used when
 invoking the executable to choose the backend.
 
 You can use the following meta ops in the REPL:
@@ -69,12 +68,15 @@ and a nicely-formatted diagnostic will be in `"display"` if available.
 > 
 > As a guard against users accidentally exposing sensitive data, 
 > If you bind Cozo to non-loopback addresses, 
-> Cozo will generate a token string and require all queries from non-loopback addresses 
+> Cozo will generate a token string and require all queries 
 > to provide the token string in the HTTP header field `x-cozo-auth`. 
 > The warning printed when you start Cozo with a 
 > non-default binding will tell you where to find the token string. 
 > This “security measure” is not considered sufficient for any purpose 
 > and is only intended as a last defence against carelessness.
+> 
+> In some environments, setting the header may be difficult or impossible
+> for some of the APIs. In this case you can pass the token in the query parameter `auth`.
 
 ## API
 
@@ -91,11 +93,22 @@ and a nicely-formatted diagnostic will be in `"display"` if available.
 > For `import` and `import-from-backup`, triggers are _not_ run for the relations, if any exists.
 If you need to activate triggers, use queries with parameters.
 
+The following are experimental:
+
+* `GET(SSE) /changes/{relation: String}` get changes when mutations are made against a relation, relies on [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
+* `GET(SSE) /rules/{name: String}` register a custom fixed rule and receive requests for computation.
+  Query parameter `arity` must also be present.
+* `POST /rule-result/{id}` post results of custom fixed rule computation back to the server, used together with the last API.
+* `POST /transact` start a multi-statement transaction, the ID returned is used in the following two APIs.
+  Need to set the `write=true` query parameter if mutations are present.
+* `POST /transact/{id}` do queries inside a multi-statement transaction, JSON payload expected is the same as for `/text-query`. 
+* `PUT /transact/{id}` commit or abort a multi-statement transaction. JSON payload is of the form `{"abort": <bool>}`, pass `false` for commit and `true` for abort. If you forget to do this, a resource leak results, even for read-only transactions.
+
 
 ## Building
 
-Building `cozoserver` requires a [Rust toolchain](https://rustup.rs). Run
+Building `cozo` requires a [Rust toolchain](https://rustup.rs). Run
 
 ```bash
-cargo build --release -p cozoserver -F compact -F storage-rocksdb
+cargo build --release -p cozo-bin -F compact -F storage-rocksdb
 ```

cozo-lib-nodejs/README-zh.md

@@ -40,7 +40,7 @@ printQuery("?[] <- [['hello', 'world', $name]]", {"name": "JavaScript"})
 printQuery("?[a] <- [[1, 2]]")
 ```
 
-### API
+### 基本 API
 
 ```ts
 class CozoDb {
@@ -110,6 +110,10 @@ class CozoDb {
 
 更多信息 [见此](https://docs.cozodb.org/zh_CN/latest/nonscript.html) 。
 
+### 进阶 API
+
+Cozo 支持多语句事务、存储表更新时回调以及使用 NodeJS 实现自定义固定规则，与 [Python 库](https://github.com/cozodb/pycozo) （[国内镜像](https://gitee.com/cozodb/pycozo)）所支持的差不多。可参考此 [示例](./example.js)。
+
 ## 编译
 
 编译 `cozo-node` 需要 [Rust 工具链](https://rustup.rs)。运行

cozo-lib-nodejs/README.md

@@ -34,7 +34,7 @@ printQuery("?[] <- [['hello', 'world', $name]]", {"name": "JavaScript"})
 printQuery("?[a] <- [[1, 2]]")
 ```
 
-### API
+### Basic API
 
 ```ts
 class CozoDb {
@@ -112,6 +112,12 @@ class CozoDb {
 
 More information are [here](https://docs.cozodb.org/en/latest/nonscript.html).
 
+### Advanced API
+
+There are API for multi-statement transactions, mutation callbacks and implementing custom fixed rules
+for NodeJS, much like the [Python counterpart](https://github.com/cozodb/pycozo). If you are interested,
+look at this [example](./example.js).
+
 ## Building
 
 Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run

cozo-lib-nodejs/example.js

@@ -17,13 +17,13 @@ const {CozoDb} = require('.');
     } catch (e) {
         console.error(e)
     }
-    const cb_id = db.register_callback('test', (op, new_rows, old_rows) => {
+    const cb_id = db.registerCallback('test', (op, new_rows, old_rows) => {
         console.log(`${op} ${JSON.stringify(new_rows)} ${JSON.stringify(old_rows)}`)
     })
 
     await db.run(`?[a] <- [[1],[2],[3]] :create test {a}`);
 
-    db.register_named_rule('Pipipy', 1, async (inputs, options) => {
+    db.registerNamedRule('Pipipy', 1, async (inputs, options) => {
         console.log(`rule inputs: ${JSON.stringify(inputs)} ${JSON.stringify(options)}`)
         await sleep(1000);
         return inputs[0].map((row) => [row[0] * options.mul])
@@ -42,7 +42,7 @@ const {CozoDb} = require('.');
 
     console.log((await db.exportRelations(['test']))['test']['rows'])
 
-    const tx = db.multi_transact(true);
+    const tx = db.multiTransact(true);
     await tx.run(':create a {a}');
     await tx.run('?[a] <- [[1]] :put a {a}');
     try {
@@ -56,8 +56,8 @@ const {CozoDb} = require('.');
     const res = await db.run('?[a] := *a[a]');
     console.log(res);
 
-    db.unregister_callback(cb_id)
-    db.unregister_named_rule('Pipipy')
+    db.unregisterCallback(cb_id)
+    db.unregisterNamedRule('Pipipy')
 })()
 
 function sleep(ms) {

cozo-lib-nodejs/index.js

@@ -47,7 +47,7 @@ class CozoDb {
         native.close_db(this.db_id)
     }
 
-    multi_transact(write) {
+    multiTransact(write) {
         return new CozoTx(native.multi_transact(this.db_id, !!write))
     }
 
@@ -124,15 +124,15 @@ class CozoDb {
         })
     }
 
-    register_callback(relation, cb, capacity = -1) {
+    registerCallback(relation, cb, capacity = -1) {
         return native.register_callback(this.db_id, relation, cb, capacity)
     }
 
-    unregister_callback(cb_id) {
+    unregisterCallback(cb_id) {
         return native.unregister_callback(this.db_id, cb_id)
     }
 
-    register_named_rule(name, arity, cb) {
+    registerNamedRule(name, arity, cb) {
         return native.register_named_rule(this.db_id, name, arity, async (ret_id, inputs, options) => {
             let ret = undefined;
             try {
@@ -150,7 +150,7 @@ class CozoDb {
         })
     }
 
-    unregister_named_rule(name) {
+    unregisterNamedRule(name) {
         return native.unregister_named_rule(this.db_id, name)
     }
 }