diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 0a8b8da4..2b3d33ca 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -12,6 +12,7 @@ - [Capability-Based Security](./process/capabilities.md) - [Startup, Spindown, and Crashes](./process/startup.md) - [Extensions](./process/extensions.md) + - [WIT APIs](./process/wit-apis.md) - [Networking Protocol](./networking_protocol.md) - [Public Key Infrastructure](./pki.md) - [HTTP Server & Client](./http_server_and_client.md) @@ -35,6 +36,7 @@ - [`connect`](./kit/connect.md) - [`reset-cache`](./kit/reset-cache.md) - [`boot-real-node`](./kit/boot-real-node.md) + - [`view-api`](./kit/view-api.md) - [My First Kinode Application](./build-and-deploy-an-app.md) - [Environment Setup](./my_first_app/chapter_1.md) - [Sending and Responding to a Message](./my_first_app/chapter_2.md) diff --git a/src/kit-dev-toolkit.md b/src/kit-dev-toolkit.md index 7a976ba0..a81fbea3 100644 --- a/src/kit-dev-toolkit.md +++ b/src/kit-dev-toolkit.md @@ -18,3 +18,4 @@ * [`kit connect`](./kit/connect.md) * [`kit reset-cache`](./kit/reset-cache.md) * [`kit boot-real-node`](./kit/boot-real-node.md) +* [`kit view-api`](./kit/view-api.md) diff --git a/src/kit/view-api.md b/src/kit/view-api.md new file mode 100644 index 00000000..77f8a9cd --- /dev/null +++ b/src/kit/view-api.md @@ -0,0 +1,59 @@ +# `kit view-api` + +`kit view-api` fetches the list of APIs or a specific API for the given package. +`view-api` relies on a node to do so, e.g. + +``` +kit view-api --port 8080 +``` + +lists all the APIs of packages downloaded by the Kinode running at port 8080. + +## Example Usage + +``` +# Fetch and display the API for the given package +kit view-api app_store:sys-v0 +``` + +## Discussion + +Currently broken! +TODO: fix & document + +## Arguments + +``` +$ kit view-api --help +Fetch the list of APIs or a specific API + +Usage: kit view-api [OPTIONS] [PACKAGE_ID] + +Arguments: + [PACKAGE_ID] Get API of this package (default: list all APIs) + +Options: + -p, --port Node port: for use on localhost (overridden by URL) [default: 8080] + -u, --url Node URL (overrides NODE_PORT) + -h, --help Print help +``` + +### Positional arg: `PACKAGE_ID` + +Get the API of this package. +By default, list the names of all APIs. + +### `--port` + +short: `-p` + +For nodes running on localhost, the port of the node; defaults to `8080`. +`--port` is overridden by `--url` if both are supplied. + +### `--url` + +short: `-u` + +The URL the node is hosted at. +Can be either localhost or remote. +`--url` overrides `--port` if both are supplied. diff --git a/src/my_first_app/chapter_1.md b/src/my_first_app/chapter_1.md index 96c40d99..d974cfa3 100644 --- a/src/my_first_app/chapter_1.md +++ b/src/my_first_app/chapter_1.md @@ -56,22 +56,40 @@ By default, the `kit new` command creates a simple, one-process package, a chat Other templates, including a Python template and a UI-enabled template can be used by passing [different flags to `kit new`](../kit/new.html#discussion). The default template looks like: -```bash +``` $ tree my_chat_app my_chat_app - ├── Cargo.toml - ├── metadata.json - ├── my_chat_app - │ ├── Cargo.toml - │ └── src - │ └── lib.rs - ├── pkg - │ ├── manifest.json - │ └── scripts.json - └── send - ├── Cargo.toml - └── src - └── lib.rs +├── api +│   └── my_chat_app:template.os-v0.wit +├── Cargo.toml +├── metadata.json +├── my_chat_app +│   ├── Cargo.toml +│   └── src +│   └── lib.rs +├── pkg +│   ├── manifest.json +│   └── scripts.json +├── send +│   ├── Cargo.toml +│   └── src +│   └── lib.rs +└── test + ├── my_chat_app_test + │   ├── api + │   │   ├── my_chat_app:template.os-v0.wit + │   │   ├── my_chat_app_test:template.os-v0.wit + │   │   └── tester:sys-v0.wit + │   ├── Cargo.toml + │   ├── metadata.json + │   ├── my_chat_app_test + │   │   ├── Cargo.toml + │   │   └── src + │   │   ├── lib.rs + │   │   └── tester_lib.rs + │   └── pkg + │   └── manifest.json + └── tests.toml ``` The `my_chat_app/` package here contains two processes: @@ -79,20 +97,27 @@ The `my_chat_app/` package here contains two processes: - `send/` — containing a [script](../cookbook/writing_scripts.html). Rust process directories, like the ones here, contain: -- `src/` - source files where the code for the process lives, and -- `Cargo.toml` - the standard Rust file specifying dependencies, etc., for that process. +- `src/` — source files where the code for the process lives, and +- `Cargo.toml` — the standard Rust file specifying dependencies, etc., for that process. Another standard Rust `Cargo.toml` file, a [virtual manifest](https://doc.rust-lang.org/cargo/reference/workspaces.html#virtual-workspace) is also included in `my_chat_app/` root. Also within the package directory is a `pkg/` directory. The `pkg/` dirctory contains two files: -- `manifest.json` - specifes information the Kinode needs to run the package, and -- `scripts.json` - specifies details needed to run [scripts](../cookbook/writing_scripts.html). +- `manifest.json` — required: specifes information the Kinode needs to run the package, and +- `scripts.json` — optional: specifies details needed to run [scripts](../cookbook/writing_scripts.html). The `pkg/` directory is also where `.wasm` binaries will be deposited by [`kit build`](#building-the-package). The files in the `pkg/` directory are injected into the Kinode with [`kit start-package`](#starting-the-package). -Lastly, `metadata.json` contains app metadata which is used in the Kinode [App Store](./chapter_5.html) +The `metadata.json` is a required file that contains app metadata which is used in the Kinode [App Store](./chapter_5.html) + +The `api/` directory contains the [WIT API](../process/wit-apis.md) for the `my_chat_app` package, see more discussion [below](#api). + +Lastly, the `test/` directory contains tests for the `my_chat_app` package. +The `tests.toml` file specifies the configuration of the tests. +The `my_chat_app_test/` direcotry is itself a package: the test for `my_chat_app`. +For more discussion of tests see [`kit run-tests`](../kit/run-tests.md), or see usage, [below](#testing-the-package). Though not included in this template, packages with a frontend have a `ui/` directory as well. For an example, look at the result of: @@ -117,7 +142,6 @@ $ cat my_chat_app/pkg/manifest.json "request_networking": true, "request_capabilities": [ "http_server:distro:sys", - "net:distro:sys" ], "grant_capabilities": [], "public": true @@ -162,14 +186,20 @@ $ cat my_chat_app/metadata.json "mirrors": [], "code_hashes": { "0.1.0": "" - } + }, + "wit_version": 0, + "dependencies": [] }, "external_url": "", "animation_url": "" } ``` -Here, the `publisher` is some default value, but for a real package, this field should contain the KNS ID of the publishing node. +Here, the `publisher` is the default value (`"template.os"`), but for a real package, this field should contain the KNS ID of the publishing node. The `publisher` can also be set with a `kit new --publisher` flag. +The `wit_version` is an optional field. +If elided, the package will use [`kinode.wit` `0.7.0`](https://github.com/kinode-dao/kinode-wit/blob/aa2c8b11c9171b949d1991c32f58591c0e881f85/kinode.wit). +If included with a value of `0`, it will use [`kinode.wit` `0.8.0`](https://github.com/kinode-dao/kinode-wit/blob/758fac1fb144f89c2a486778c62cbea2fb5840ac/kinode.wit). +The `dependencies` field is also optional; see discussion in [WIT APIs](../process/wit-apis.md). The rest of these fields are not required for development, but become important when publishing a package with the [`app_store`](https://github.com/kinode-dao/kinode/tree/main/kinode/packages/app_store). As an aside: each process has a unique `ProcessId`, used to address messages to that process, that looks like @@ -180,6 +210,13 @@ As an aside: each process has a unique `ProcessId`, used to address messages to You can read more about `ProcessId`s [here](../process/processes.md#overview). +### `api/` + +The `api/` directory is an optional directory where packages can declare their public API. +Other packages can then mark a package as a dependency in their `metadata.json` and + +For further reading, see discussion in [WIT APIs](../process/wit-apis.md), and [`kit view-api`](../kit/view-api.md). + ## Building the Package To build the package, use the [`kit build`](../kit/build.md#) tool. @@ -319,3 +356,19 @@ kit inject-message my_chat_app:my_chat_app:template.os '{"Send": {"target": "fak kit inject-message my_chat_app:my_chat_app:template.os '{"Send": {"target": "fake.dev", "message": "replying from fake2.dev using first method..."}}' --node fake2.dev kit inject-message my_chat_app:my_chat_app:template.os '{"Send": {"target": "fake.dev", "message": "and second!"}}' -p 8081 ``` + +## Testing the Package + +To run the `my_chat_app/` tests, close all fake nodes and then run + +```bash +kit run-tests my_chat_app +``` + +or, if already in the `my_chat_app/` package directory: + +```bash +kit run-tests +``` + +For more details, see [`kit run-tests`](../kit/run-tests.md). diff --git a/src/process/wit-apis.md b/src/process/wit-apis.md new file mode 100644 index 00000000..17667bd0 --- /dev/null +++ b/src/process/wit-apis.md @@ -0,0 +1,20 @@ +# WIT APIs + +Kinode OS runs processes that are WebAssembly components, as discussed [elsewhere](./processes.md#wasm-and-kinode). +Two key advantages of WebAssembly components are + +1. The declaration of types and functions using the cross-language Wasm Interface Type (WIT) language +2. The composibility of components. +See discussion [here](https://component-model.bytecodealliance.org/design/why-component-model.html). + +Kinode processes make use of these two advantages. +Processes within a package — a group of processes, also referred to as an app — may define an API in WIT format. +Each process defines a [WIT interface](https://component-model.bytecodealliance.org/design/wit.html#interfaces); the package defines a [WIT world](https://component-model.bytecodealliance.org/design/wit.html#interfaces). +The API is published alongside the package. +Other packages may then import and depend upon that API, and thus communicate with the processes in that package. +The publication of the API also allows for easy inspection by developers or by machines, e.g., LLM agents. + +More than types can be published. +Because components are composable, packages may publish, along with the types in their API, library functions that may be of use in interacting with that package. +When set as as a dependency, these functions will be composed into new packages. +Libraries unassociated with packages can also be published and composed.