From f63a2cd7d1c42978cab209c0bb642b441aa4ecc2 Mon Sep 17 00:00:00 2001 From: Ziyang Hu Date: Sat, 21 Jan 2023 17:49:30 +0800 Subject: [PATCH] update docs for new version --- README-zh.md | 22 +++++++++++----------- README.md | 4 ++-- cozo-bin/README-zh.md | 25 ++++++++++++++++++------- cozo-bin/README.md | 33 +++++++++++++++++++++++---------- cozo-lib-nodejs/README-zh.md | 6 +++++- cozo-lib-nodejs/README.md | 8 +++++++- cozo-lib-nodejs/example.js | 10 +++++----- cozo-lib-nodejs/index.js | 10 +++++----- 8 files changed, 76 insertions(+), 42 deletions(-) diff --git a/README-zh.md b/README-zh.md index 3a52c0c4..b5622a73 100644 --- a/README-zh.md +++ b/README-zh.md @@ -168,19 +168,19 @@ 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 | +| 语言/环境 | 官方支持的平台 | 存储引擎 | +|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------| +| [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 | | [Java (JVM)](https://github.com/cozodb/cozo-lib-java)（[国内镜像](https://gitee.com/cozodb/cozo-lib-java)） | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | | [Clojure (JVM)](https://github.com/cozodb/cozo-clj)（[国内镜像](https://gitee.com/cozodb/cozo-clj)） | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | | [安卓](https://github.com/cozodb/cozo-lib-android)（[国内镜像](https://gitee.com/cozodb/cozo-lib-android)） | Android (ARM64, ARMv7, x86_64, x86) | MQ | -| [iOS/macOS (Swift)](./cozo-lib-swift) | iOS (ARM64, 模拟器), Mac (ARM64, x86_64) | MQ | -| [Rust](https://docs.rs/cozo/) | 任何支持`std`的[平台](https://doc.rust-lang.org/nightly/rustc/platform-support.html)（源代码编译） | MQRST | +| [iOS/macOS (Swift)](./cozo-lib-swift) | iOS (ARM64, 模拟器), Mac (ARM64, x86_64) | MQ | +| [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 | +| [C/C++/支持 C FFI 的语言](./cozo-lib-c) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | +| [独立的 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）。 diff --git a/README.md b/README.md index 178ad657..c1ded05f 100644 --- a/README.md +++ b/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! diff --git a/cozo-bin/README-zh.md b/cozo-bin/README-zh.md index 76e4de43..b451335a 100644 --- a/cozo-bin/README-zh.md +++ b/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": }`，传入真值则放弃，否则提交。如果不执行此查询则服务器会浪费系统资源。 + ## 编译 -编译 `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 ``` diff --git a/cozo-bin/README.md b/cozo-bin/README.md index 4a0195aa..6df2d145 100644 --- a/cozo-bin/README.md +++ b/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": }`, 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 ``` diff --git a/cozo-lib-nodejs/README-zh.md b/cozo-lib-nodejs/README-zh.md index 6ce93638..960c9813 100644 --- a/cozo-lib-nodejs/README-zh.md +++ b/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)。运行 diff --git a/cozo-lib-nodejs/README.md b/cozo-lib-nodejs/README.md index 6032f499..92bcadd7 100644 --- a/cozo-lib-nodejs/README.md +++ b/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 diff --git a/cozo-lib-nodejs/example.js b/cozo-lib-nodejs/example.js index abbd3eef..f0cd14bc 100644 --- a/cozo-lib-nodejs/example.js +++ b/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) { diff --git a/cozo-lib-nodejs/index.js b/cozo-lib-nodejs/index.js index 6a3c22df..48639087 100644 --- a/cozo-lib-nodejs/index.js +++ b/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) } }