@graftland/plugin-remote 0.3.2 → 0.4.0

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
 
-Run a Graft plugin in a child process, a Node worker, or on a runner. Declare
-cross-boundary services in a contract; consumers keep their usual interfaces.
-The host imports only the contract, whose `module` points to the implementation.
-Build both to JavaScript.
+Run a Graft plugin somewhere else: in a child process, in a Node worker, or on
+another machine through a runner. The plugins that use it keep injecting its
+[services](https://graftland.github.io/graft/services/) as usual; only its
+[config entry](https://graftland.github.io/graft/config-file/) changes.
 
 ```yaml
 - id: greeter
@@ -16,62 +16,26 @@ Build both to JavaScript.
     config: { greeting: Hello }
 ```
 
-Use `graft start`, or load this TypeScript plugin with `Graft.plugin(entry)`:
+Remote isolates execution, not permissions. For a permission boundary, run the
+runner in a container or a VM.
 
-```ts
-import * as Remote from "@graftland/plugin-remote"
-import { contract } from "./contract.js"
+## Documentation
 
-export default Remote.plugin(contract, {
-	contractModule: new URL("./contract.js", import.meta.url).href,
-	connect: { worker: {} },
-	config: { greeting: "Hello" },
-})
-```
-
-TS and YAML share `connect`: local, worker, url (ws/wss), unix, or command. Auth
-is mtls, bearer, jwt, none, or a third-party `{ name, config }` reference. No
-separate capability entries or service-key strings are needed. TS credentials
-can also be Effects or `{ inject, read }`. A custom host supplies
-`NodeServices.layer` and `SecureRandom.layerWebCrypto` to Graft.
-
-A runner configuration:
-
-```yaml
-- name: remote/runner
-  config:
-    root: ./installation
-    state: ./state
-    listen:
-      - url: wss://0.0.0.0:7443
-        cert: ./certs/server.crt
-        key: ./certs/server.key
-        auth: { mtls: { ca: ./certs/ca.crt } }
-```
-
-Run `graft-remote serve --config runner.yml`. Install its plugin packages in
-advance, preserve the state directory, and supervise the runner and descendants.
-`graft-remote certificates` can issue certificates. A saved host entry id names
-the instance by default; the runner confirms old-process exit before replacement
-and advances generation. Read the guide for leases and three stopping outcomes.
+- [Remote](https://graftland.github.io/graft/remote/overview/): what Remote does
+  and its limits.
+- [Host entries](https://graftland.github.io/graft/remote/hosts/): contracts,
+  `remote` entries, services and errors.
+- [Runners](https://graftland.github.io/graft/remote/runners/): run plugins on
+  another machine with `graft start runner.yml`.
+- [Transport and authentication](https://graftland.github.io/graft/remote/transport-auth/)
+- [Replacement and stopping](https://graftland.github.io/graft/remote/lifecycle/)
+- [Capability plugins](https://graftland.github.io/graft/remote/capabilities/)
+- [API reference](https://graftland.github.io/graft/reference/plugin-remote/readme/)
 
-Workers do not isolate permissions. Unix relies on file permissions; stdio
-relies on SSH or another external mechanism. Use wss for tokens; stolen tokens
-can be replayed while valid. JWT is checked once at upgrade. Restart the host
-after changing a contract; contract imports do not participate in HMR.
+## Samples
 
-Public APIs: root default, `plugin`, `Contract`, `Instance`, public errors;
-`/runner`; `/Auth`, `/Transport`, `/Errors`, `/Contract`, `/Testing`; and
-capability modules under `host/*` and `runner/*`. The executable paths
-`/internal/bin`, `/internal/worker`, `/internal/watchdog` are **not public
-APIs**.
-
-- [Remote](https://graftland.github.io/graft/remote/overview/)
-- [Capabilities](https://graftland.github.io/graft/remote/capabilities/)
 - [06 · Remote](../../samples/06-remote/)
 - [Chat bot](../../samples/chat-bot/)
 
-This workspace package remains private.
-
 Part of [Graft](https://github.com/graftland/graft). Licensed under
 [Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE).

package/README.zh-CN.md

@@ -1,10 +1,9 @@
 # @graftland/plugin-remote
 
-English | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
+[English](README.md) | 简体中文 | [繁體中文](README.zh-TW.md)
 
-在子进程、Node
-worker 或 runner 上运行 Graft 插件。契约声明跨边界的服务，消费者保留原来的接口。宿主只导入契约，契约的
-`module` 指向实现；先把两者构建成 JavaScript。
+把 Graft 插件放到别处运行：子进程、Node
+worker，或通过 runner 放到另一台机器上。使用它的插件照常注入它的[服务](https://graftland.github.io/graft/zh-cn/services/)，要改的只有它的[配置条目](https://graftland.github.io/graft/zh-cn/config-file/)。
 
 ```yaml
 - id: greeter
@@ -15,57 +14,24 @@ worker 或 runner 上运行 Graft 插件。契约声明跨边界的服务，消
     config: { greeting: Hello }
 ```
 
-运行 `graft start`，或用 `Graft.plugin(entry)` 加载 TS 插件：
+Remote 隔离的是执行，不是权限。需要权限边界时，请把 runner 放进容器或虚拟机。
 
-```ts
-import * as Remote from "@graftland/plugin-remote"
-import { contract } from "./contract.js"
+## 文档
 
-export default Remote.plugin(contract, {
-	contractModule: new URL("./contract.js", import.meta.url).href,
-	connect: { worker: {} },
-	config: { greeting: "Hello" },
-})
-```
-
-TS 和 YAML 共用
-`connect`：local、worker、url（ws/wss）、unix、command。认证可以选 mtls、bearer、jwt、none，或第三方
-`{ name, config }`
-引用。不必另写能力 entry 或服务键字符串。TS 凭证还允许 Effect 或
-`{ inject, read }`。自定义宿主需为 Graft 提供 `NodeServices.layer` 和
-`SecureRandom.layerWebCrypto`。
-
-runner 配置：
-
-```yaml
-- name: remote/runner
-  config:
-    root: ./installation
-    state: ./state
-    listen:
-      - url: wss://0.0.0.0:7443
-        cert: ./certs/server.crt
-        key: ./certs/server.key
-        auth: { mtls: { ca: ./certs/ca.crt } }
-```
-
-运行
-`graft-remote serve --config runner.yml`。提前安装插件包，保留状态目录，并由外部 supervisor 管理 runner 及后代进程。`graft-remote certificates`
-可生成证书。宿主保存的条目 id 默认就是实例名；runner 确认旧进程退出后才接纳替换，并递增 generation。租约和三种停止结果见指南。
-
-worker 不隔离权限；unix 依赖文件权限；stdio 依赖 SSH 等外部机制。token 建议走 wss，被盗后在有效期内可以重放。JWT 只在 upgrade 验证一次。修改契约后须重启宿主，契约导入不参与 HMR。
-
-公开 API：包根 default、`plugin`、`Contract`、`Instance`、公开错误；`/runner`；`/Auth`、`/Transport`、`/Errors`、`/Contract`、`/Testing`；以及
-`host/*`、`runner/*`
-能力模块。`/internal/bin`、`/internal/worker`、`/internal/watchdog`
-只是可执行文件路径，**不是公开 API**。
+- [Remote](https://graftland.github.io/graft/zh-cn/remote/overview/)：Remote 做什么，有哪些局限。
+- [宿主条目](https://graftland.github.io/graft/zh-cn/remote/hosts/)：契约、`remote`
+  条目、服务与错误。
+- [Runner](https://graftland.github.io/graft/zh-cn/remote/runners/)：用
+  `graft start runner.yml` 在另一台机器上运行插件。
+- [传输与认证](https://graftland.github.io/graft/zh-cn/remote/transport-auth/)
+- [替换与停止](https://graftland.github.io/graft/zh-cn/remote/lifecycle/)
+- [能力插件](https://graftland.github.io/graft/zh-cn/remote/capabilities/)
+- [API 参考](https://graftland.github.io/graft/reference/plugin-remote/readme/)
 
-- [Remote](https://graftland.github.io/graft/zh-cn/remote/overview/)
-- [Capabilities](https://graftland.github.io/graft/zh-cn/remote/capabilities/)
-- [06 · Remote](../../samples/06-remote/)
-- [Chat bot](../../samples/chat-bot/)
+## 示例
 
-本工作区包仍为 private。
+- [06 · 远程插件](../../samples/06-remote/README.zh-CN.md)
+- [聊天机器人](../../samples/chat-bot/README.zh-CN.md)
 
 Part of [Graft](https://github.com/graftland/graft). Licensed under
 [Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE).

package/README.zh-TW.md

@@ -1,10 +1,9 @@
 # @graftland/plugin-remote
 
-English | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
+[English](README.md) | [简体中文](README.zh-CN.md) | 繁體中文
 
-在子行程、Node
-worker 或 runner 執行 Graft 外掛。契約宣告跨邊界的服務，消費者保留原來的介面。宿主只匯入契約，契約的
-`module` 指向實作；先將兩者建置為 JavaScript。
+把 Graft 外掛放到別處執行：子行程、Node
+worker，或透過 runner 放到另一台機器上。使用它的外掛照常注入它的[服務](https://graftland.github.io/graft/zh-tw/services/)，需要改的只有它的[設定項目](https://graftland.github.io/graft/zh-tw/config-file/)。
 
 ```yaml
 - id: greeter
@@ -15,57 +14,24 @@ worker 或 runner 執行 Graft 外掛。契約宣告跨邊界的服務，消費
     config: { greeting: Hello }
 ```
 
-執行 `graft start`，或以 `Graft.plugin(entry)` 載入 TS 外掛：
+Remote 隔離的是執行，不是權限。需要權限邊界時，請把 runner 放進容器或虛擬機器。
 
-```ts
-import * as Remote from "@graftland/plugin-remote"
-import { contract } from "./contract.js"
+## 文件
 
-export default Remote.plugin(contract, {
-	contractModule: new URL("./contract.js", import.meta.url).href,
-	connect: { worker: {} },
-	config: { greeting: "Hello" },
-})
-```
-
-TS 與 YAML 共用
-`connect`：local、worker、url（ws/wss）、unix、command。驗證可選 mtls、bearer、jwt、none，或第三方
-`{ name, config }`
-引用。不必另寫能力 entry 或服務鍵字串。TS 憑證也允許 Effect 或
-`{ inject, read }`。自訂宿主須為 Graft 提供 `NodeServices.layer` 與
-`SecureRandom.layerWebCrypto`。
-
-runner 設定：
-
-```yaml
-- name: remote/runner
-  config:
-    root: ./installation
-    state: ./state
-    listen:
-      - url: wss://0.0.0.0:7443
-        cert: ./certs/server.crt
-        key: ./certs/server.key
-        auth: { mtls: { ca: ./certs/ca.crt } }
-```
-
-執行
-`graft-remote serve --config runner.yml`。預先安裝外掛套件，保留狀態目錄，並由外部 supervisor 管理 runner 及後代行程。`graft-remote certificates`
-可產生憑證。宿主保存的條目 id 預設就是實例名稱；runner 確認舊行程退出後才接受替換，並遞增 generation。租約與三種停止結果見指南。
-
-worker 不隔離權限；unix 依賴檔案權限；stdio 依賴 SSH 等外部機制。token 建議走 wss，被竊後在有效期內可以重放。JWT 只在 upgrade 驗證一次。修改契約後須重啟宿主，契約匯入不參與 HMR。
-
-公開 API：套件根目錄 default、`plugin`、`Contract`、`Instance`、公開錯誤；`/runner`；`/Auth`、`/Transport`、`/Errors`、`/Contract`、`/Testing`；以及
-`host/*`、`runner/*`
-能力模組。`/internal/bin`、`/internal/worker`、`/internal/watchdog`
-僅是執行檔路徑，**不是公開 API**。
+- [Remote](https://graftland.github.io/graft/zh-tw/remote/overview/)：Remote 做什麼，以及它的限制。
+- [宿主設定項目](https://graftland.github.io/graft/zh-tw/remote/hosts/)：契約、`remote`
+  設定項目、服務與錯誤。
+- [Runner](https://graftland.github.io/graft/zh-tw/remote/runners/)：用
+  `graft start runner.yml` 在另一台機器上執行外掛。
+- [傳輸與驗證](https://graftland.github.io/graft/zh-tw/remote/transport-auth/)
+- [替換與停止](https://graftland.github.io/graft/zh-tw/remote/lifecycle/)
+- [能力外掛](https://graftland.github.io/graft/zh-tw/remote/capabilities/)
+- [API 參考](https://graftland.github.io/graft/reference/plugin-remote/readme/)
 
-- [Remote](https://graftland.github.io/graft/zh-tw/remote/overview/)
-- [Capabilities](https://graftland.github.io/graft/zh-tw/remote/capabilities/)
-- [06 · Remote](../../samples/06-remote/)
-- [Chat bot](../../samples/chat-bot/)
+## 範例
 
-此工作區套件仍為 private。
+- [06 · 遠端外掛](../../samples/06-remote/README.zh-TW.md)
+- [聊天機器人](../../samples/chat-bot/README.zh-TW.md)
 
 Part of [Graft](https://github.com/graftland/graft). Licensed under
 [Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE).

package/dist/Auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Auth.d.ts","names":[],"sources":["../src/Auth.ts"],"mappings":";;iBASiB;WACP;WACA,KAAK,SAAS;;iBAEP;WACP,KAAK;WACL,gBAAgB,OAAO;;iBAEhB;WACP,IAAI;WACJ;WACA;WACA;;YAEE;WAEA;WACA,OAAO,SAAS;;WAEd;WAA8B,OAAO;;WACrC;;YAEF,oBACV,KAAK;WACI,MAAM;WACN,MAAM,OAAO,OACrB,QAAQ;aAAqB,MAAM;MACnC,kBACA,MAAM;KAGP;YAEU;WAEA;WACA;WACA,eACR,QAAQ,OAAO,OAAO,SAAS,sBAC3B,OAAO,eAEX,uBAAuB;;WAIf;WACA,KAAK;WACL,eACR,MAAM,wBACF,OAAO,eAAe;;WAEhB;WAAuB;;;qBAExB,oBAAoB;;qBAGpB,sBAAsB"}
+{"version":3,"file":"Auth.d.ts","names":[],"sources":["../src/Auth.ts"],"mappings":";;iBAeiB;WACP;WACA,KAAK,SAAS;;iBAEP;WACP,KAAK;WACL,gBAAgB,OAAO;;iBAEhB;WACP,IAAI;WACJ;WACA;WACA;;YAEE;WAEA;WACA,OAAO,SAAS;;WAEd;WAA8B,OAAO;;WACrC;;YAEF,oBACV,KAAK;WACI,MAAM;WACN,MAAM,OAAO,OACrB,QAAQ;aAAqB,MAAM;MACnC,kBACA,MAAM;KAGP;YAEU;WAEA;WACA;WACA,eACR,QAAQ,OAAO,OAAO,SAAS,sBAC3B,OAAO,eAEX,uBAAuB;;WAIf;WACA,KAAK;WACL,eACR,MAAM,wBACF,OAAO,eAAe;;WAEhB;WAAuB;;;qBAExB,oBAAoB;;qBAGpB,sBAAsB"}

package/dist/Auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"Auth.js","names":[],"sources":["../src/Auth.ts"],"sourcesContent":["/** Credentials and authenticated identities shared by transport plugins. */\nimport { Context } from \"effect\"\nimport type { Effect, Redacted, Option, Scope } from \"effect\"\nimport type {\n\tAuthenticationFailed,\n\tAuthenticatorUnavailable,\n\tCredentialsError,\n} from \"./Errors\"\n\nexport interface ClientCertificate {\n\treadonly cert: string\n\treadonly key: Redacted.Redacted<string>\n}\nexport interface VerifiedCertificate {\n\treadonly der: Uint8Array\n\treadonly subjectAltName: Option.Option<string>\n}\nexport interface TlsPolicy {\n\treadonly ca: ReadonlyArray<string>\n\treadonly minVersion: \"TLSv1.3\"\n\treadonly requestCert: true\n\treadonly rejectUnauthorized: true\n}\nexport type Prepared =\n\t| {\n\t\t\treadonly _tag: \"Authorization\"\n\t\t\treadonly value: Redacted.Redacted<string>\n\t  }\n\t| { readonly _tag: \"Certificate\"; readonly value: ClientCertificate }\n\t| { readonly _tag: \"None\" }\n\nexport type CredentialsApi = {\n\t[K in Prepared[\"_tag\"]]: {\n\t\treadonly kind: K\n\t\treadonly read: Effect.Effect<\n\t\t\tExtract<Prepared, { readonly _tag: K }>,\n\t\t\tCredentialsError,\n\t\t\tScope.Scope\n\t\t>\n\t}\n}[Prepared[\"_tag\"]]\n\nexport type AuthenticatorApi =\n\t| {\n\t\t\treadonly _tag: \"Header\"\n\t\t\treadonly issuer?: string\n\t\t\treadonly authenticate: (\n\t\t\t\theader: Option.Option<Redacted.Redacted<string>>,\n\t\t\t) => Effect.Effect<\n\t\t\t\tstring,\n\t\t\t\tAuthenticationFailed | AuthenticatorUnavailable\n\t\t\t>\n\t  }\n\t| {\n\t\t\treadonly _tag: \"Mtls\"\n\t\t\treadonly tls: TlsPolicy\n\t\t\treadonly authenticate: (\n\t\t\t\tpeer: VerifiedCertificate,\n\t\t\t) => Effect.Effect<string, AuthenticationFailed>\n\t  }\n\t| { readonly _tag: \"None\"; readonly identity: string }\n\nexport class Credentials extends Context.Service<Credentials, CredentialsApi>()(\n\t\"@graftland/plugin-remote/Auth/Credentials\",\n) {}\nexport class Authenticator extends Context.Service<\n\tAuthenticator,\n\tAuthenticatorApi\n>()(\"@graftland/plugin-remote/Auth/Authenticator\") {}\n"],"mappings":";;;AA8DA,IAAa,cAAb,cAAiC,QAAQ,QAAqC,CAAC,CAC9E,2CACD,CAAC,CAAC,CAAC;AACH,IAAa,gBAAb,cAAmC,QAAQ,QAGzC,CAAC,CAAC,6CAA6C,CAAC,CAAC,CAAC"}
+{"version":3,"file":"Auth.js","names":[],"sources":["../src/Auth.ts"],"sourcesContent":["/** Credentials and authenticated identities shared by transport plugins. */\nimport {\n\tContext,\n\ttype Effect,\n\ttype Option,\n\ttype Redacted,\n\ttype Scope,\n} from \"effect\"\n\nimport type {\n\tAuthenticationFailed,\n\tAuthenticatorUnavailable,\n\tCredentialsError,\n} from \"./Errors\"\n\nexport interface ClientCertificate {\n\treadonly cert: string\n\treadonly key: Redacted.Redacted<string>\n}\nexport interface VerifiedCertificate {\n\treadonly der: Uint8Array\n\treadonly subjectAltName: Option.Option<string>\n}\nexport interface TlsPolicy {\n\treadonly ca: ReadonlyArray<string>\n\treadonly minVersion: \"TLSv1.3\"\n\treadonly requestCert: true\n\treadonly rejectUnauthorized: true\n}\nexport type Prepared =\n\t| {\n\t\t\treadonly _tag: \"Authorization\"\n\t\t\treadonly value: Redacted.Redacted<string>\n\t  }\n\t| { readonly _tag: \"Certificate\"; readonly value: ClientCertificate }\n\t| { readonly _tag: \"None\" }\n\nexport type CredentialsApi = {\n\t[K in Prepared[\"_tag\"]]: {\n\t\treadonly kind: K\n\t\treadonly read: Effect.Effect<\n\t\t\tExtract<Prepared, { readonly _tag: K }>,\n\t\t\tCredentialsError,\n\t\t\tScope.Scope\n\t\t>\n\t}\n}[Prepared[\"_tag\"]]\n\nexport type AuthenticatorApi =\n\t| {\n\t\t\treadonly _tag: \"Header\"\n\t\t\treadonly issuer?: string\n\t\t\treadonly authenticate: (\n\t\t\t\theader: Option.Option<Redacted.Redacted<string>>,\n\t\t\t) => Effect.Effect<\n\t\t\t\tstring,\n\t\t\t\tAuthenticationFailed | AuthenticatorUnavailable\n\t\t\t>\n\t  }\n\t| {\n\t\t\treadonly _tag: \"Mtls\"\n\t\t\treadonly tls: TlsPolicy\n\t\t\treadonly authenticate: (\n\t\t\t\tpeer: VerifiedCertificate,\n\t\t\t) => Effect.Effect<string, AuthenticationFailed>\n\t  }\n\t| { readonly _tag: \"None\"; readonly identity: string }\n\nexport class Credentials extends Context.Service<Credentials, CredentialsApi>()(\n\t\"@graftland/plugin-remote/Auth/Credentials\",\n) {}\nexport class Authenticator extends Context.Service<\n\tAuthenticator,\n\tAuthenticatorApi\n>()(\"@graftland/plugin-remote/Auth/Authenticator\") {}\n"],"mappings":";;;AAoEA,IAAa,cAAb,cAAiC,QAAQ,QAAqC,CAAC,CAC9E,2CACD,CAAC,CAAC,CAAC;AACH,IAAa,gBAAb,cAAmC,QAAQ,QAGzC,CAAC,CAAC,6CAA6C,CAAC,CAAC,CAAC"}