crate-plugin-kit 0.0.0

A cargo-based plugin system: install cdylib plugins from crates.io and load them at runtime.
Documentation
# crate-plugin-kit

[![Release](https://github.com/imba97/crate-plugin-kit/actions/workflows/release.yaml/badge.svg)](https://github.com/imba97/crate-plugin-kit/actions/workflows/release.yaml)
[![crates.io](https://img.shields.io/crates/v/crate-plugin-kit.svg)](https://crates.io/crates/crate-plugin-kit)
[![docs.rs](https://img.shields.io/docsrs/crate-plugin-kit)](https://docs.rs/crate-plugin-kit)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](#license)
[![MSRV](https://img.shields.io/badge/rust-1.88%2B-blue.svg)](#requirements)

> 中文版见 [README_CN.md]README_CN.md

A **cargo-based plugin system**: install `cdylib` plugins from crates.io and load them at
runtime. The Rust counterpart of [`npm-plugin-kit`](https://github.com/imba97/npm-plugin-kit) —
"install a plugin, then load it" — moved onto cargo.

```console
$ cargo install my-plugin          # the plugin is a cdylib crate
error: there is nothing to install

$ # crate-plugin-kit does this instead:
  myapp-plugin-foo  0.1.0
    wrapper   ~/.myapp/build/myapp-plugin-foo/          cargo build --release
    library   ~/.myapp/plugins/myapp-plugin-foo/libmyapp_plugin_foo.so
    manifest  ~/.myapp/plugins/myapp-plugin-foo/myapp-plugin.toml
```

## Features

- 🔌 **Runtime loading, zero compile-time coupling** — plugins are `cdylib`s, `dlopen`ed on
  demand. Nothing is linked into your binary.
- 🧩 **Generic, not type-erased** — `load()` hands back a thin `*const T`, never a `dyn Trait`.
  No fat-pointer conversion, so no UB at the boundary.
- 🏷️ **Every host-specific name is configuration** — app id, manifest name, crate prefix,
  entry symbol, wrapper body. This crate hardcodes none of them.
- 📦 **Install straight from crates.io** — one call, no manual downloads or vendoring.
- 🔨 **Build-host by default** — installs go through `cargo build`, so whatever registry or
  mirror you already configured just works.
- ⚡ **Prebuilt accelerator** — optionally pull a ready-made cdylib from GitHub Releases,
  falling back to a local build on any failure.
- 📄 **The manifest travels with the code** — a plugin's metadata lives in its own repo root
  and is copied at install time, so it can never drift from the implementation.
- 🔒 **Cross-process install lock** — two terminals cannot corrupt the store.
- 🚫 **Refuses unsafe unloads** — unlinking a library that is still loaded is rejected, not
  attempted. Guessing wrong there is UB.
- 🪶 **Zero async** — no runtime, no `tokio`. Installing is a subprocess, loading is `dlopen`.
- 📚 **Fully documented public API** — `#![deny(missing_docs)]`.

## Contents

- [Why this exists]#why-this-exists
- [Install]#install
- [Quick start]#quick-start
- [Configuration]#configuration
- [On-disk layout]#on-disk-layout
- [How install works]#how-install-works
- [Prebuilt assets]#prebuilt-assets
- [Where the manifest comes from]#where-the-manifest-comes-from
- [What it does not do]#what-it-does-not-do
- [Development]#development
- [Repository]#repository
- [License]#license

## Why this exists

`cargo install` only installs **bin targets**. A crate with `crate-type = ["cdylib"]` has no
bin, so installing it fails outright:

```console
$ cargo install my-plugin
error: there is nothing to install
```

Adding a bin target does not help either — `cargo install` would put that bin in
`~/.cargo/bin` and still leave the cdylib nowhere useful. And building the plugin crate
directly does not work, because Cargo builds dependencies as rlibs and never emits a cdylib
for them.

So this crate generates a tiny **wrapper project** instead, which lets the plugin itself stay
an ordinary rlib:

```text
plugin crate  (an ordinary rlib on crates.io)
    │  as a dependency
    ▼
wrapper project  (generated here, ~30 lines, [lib] crate-type = ["cdylib"])
    │  cargo build --release
    ▼
libxxx.so / xxx.dll / libxxx.dylib
    │  copied to <data-dir>/plugins/<crate>/
    ▼
dlopen at runtime
```

Because the plugin stays an rlib:

- it is an ordinary crate to the rest of the ecosystem;
- it can be unit-tested with a plain `use`, without going anywhere near `dlopen`;
- its author writes **no `#[no_mangle]` at all** — the cdylib's shape is generated by the
  host contract crate's `export!` macro.

## Install

```bash
cargo add crate-plugin-kit
```

### Requirements

- **Rust 1.88+** to build (this is the MSRV — `libloading` 0.9 requires 1.88).
- **`cargo` on `PATH`** at run time, for the default build-host install path. It is not linked
  in — installs are a subprocess. The prebuilt path does not need it.
- Linux, macOS and Windows.

## Quick start

```rust
use crate_plugin_kit::{CratePluginKit, KitConfig};

// The `#[repr(C)]` entry struct your contract crate defines.
#[repr(C)]
struct MyHostEntry {
    abi_version: u32,
    // ...
}

let mut cfg = KitConfig::new("myapp");
cfg.crate_prefix   = "myapp-plugin-".into();
cfg.entry_symbol   = b"myapp_plugin_entry_v1".to_vec();
cfg.contract_crate = "myapp-plugin".into();
cfg.wrapper_body   = "myapp_plugin::export!({crate_ident}::create);\n".into();

let kit = CratePluginKit::<MyHostEntry>::new(cfg)?;

kit.install("foo", None)?;                    // installs myapp-plugin-foo
for info in kit.list()? {
    println!("{} {}", info.name, info.version);
}

let plugin = kit.load("myapp-plugin-foo")?;   // *const MyHostEntry
let entry: *const MyHostEntry = plugin.entry();
```

`name` accepts a short name (`"foo"`, the crate prefix is added for you) or a full crate name.
Pass `None` as the version to take the latest from crates.io.

## Configuration

[`KitConfig`](https://docs.rs/crate-plugin-kit/latest/crate_plugin_kit/struct.KitConfig.html)
is where **every host-specific name lives**. This crate hardcodes none of them.

| Field | Meaning |
| --- | --- |
| `id` | App id. Data dir becomes `~/.{id}`. Also used in the HTTP User-Agent. |
| `manifest_name` | Plugin manifest filename, e.g. `myapp-plugin.toml`. |
| `crate_prefix` | Plugin crate prefix. `install("foo")` → `myapp-plugin-foo`. |
| `entry_symbol` | Exported symbol to look up, e.g. `myapp_plugin_entry_v1`. |
| `lib_stem_prefix` | cdylib filename prefix, e.g. `myapp_plugin_`. |
| `contract_crate` / `contract_version` | The host's contract crate — the generated wrapper depends on it. |
| `wrapper_edition` / `wrapper_body` | Generated wrapper's `edition` and `src/lib.rs` body. `{crate_ident}` is substituted. |
| `data_dir` | Override `~/.{id}`. Useful for tests. |
| `lock_timeout` | How long to wait for the install lock. Default 30s. |
| `prefer_prebuilt` | Try GitHub Releases before falling back to a local build. Default `true`. |
| `target_triple` | Override the compile-time target. |
| `registry` | crates.io base URL. Point it at a mirror if you like. |
| `local_overrides` | `crate name → local path`. Becomes the wrapper's `[patch.crates-io]`. **Dev only.** |

`KitConfig::new(id)` fills in conservative defaults; you must at least set `crate_prefix`,
`entry_symbol`, `lib_stem_prefix`, `contract_crate` and `wrapper_body`, or the generated
wrapper will not compile.

### Why `local_overrides` is needed

The wrapper lives under `<data-dir>/build/`, so it **cannot see your project's
`.cargo/config.toml`**. To make a wrapper build against a local checkout during development,
the host has to say so explicitly, and this crate writes it into the wrapper's own
`[patch.crates-io]`.

## On-disk layout

```text
~/.{id}/
├── plugins/
│   ├── myapp-plugin-foo/
│   │   ├── myapp-plugin.toml     ← manifest (written at install time)
│   │   └── libmyapp_plugin_foo.so
│   └── .plugins.json             ← install record cache
├── build/                        ← generated wrappers
│   └── myapp-plugin-foo/
└── .lock                         ← cross-process install lock
```

`.plugins.json` is a **cache, not a source of truth**. Lose it or corrupt it and `list()`
rebuilds from the manifests on disk.

## How install works

Two paths. **build-host is the default**, because it shells out to `cargo` and therefore
honours whatever registry or mirror the user already configured. The prebuilt path goes to
GitHub, which bypasses all of that — so it is only ever an accelerator.

| Path | What it does | Requires |
| --- | --- | --- |
| **build-host** (default) | generate wrapper → `cargo build --release` → copy artifact | a Rust toolchain |
| **prebuilt** | download cdylib + manifest from GitHub Releases | the plugin author published assets |

```text
install(name, version)
  ├─ take the lock at <data-dir>/.lock
  ├─ normalise the crate name (add the prefix)
  ├─ resolve the version (query crates.io when None)
  ├─ drop any previous install directory
  ├─ [prefer_prebuilt] try prebuilt ── ok ──▶ done
  │                                   └─ unavailable ─┐
  └─────────────────────────────────────────────────◄─┘
     generate wrapper → cargo metadata → cargo build --release
     → find the cdylib → copy cdylib + manifest → update .plugins.json
```

If prebuilt is unavailable for any reason — never published, 404, network failure — install
**silently falls back to build-host**. The two paths are independent, and the `cargo` one
often succeeds where GitHub is unreachable.

`cargo build` inherits stdio, so you see its progress. That step can take minutes; swallowing
the output would be a poor experience.

Versions are pinned exactly (`=x.y.z`), so the version recorded in `.plugins.json` and the
cdylib that was actually built can never disagree.

## Prebuilt assets

Two **raw files** rather than an archive, which saves pulling in the tar, gzip and zip
crates:

```text
{crate}-{version}-{target}.{so|dylib|dll}   ← the cdylib
{crate}-{version}-{target}.toml             ← the manifest
```

For example:

```text
myapp-plugin-foo-0.1.0-x86_64-pc-windows-msvc.dll
myapp-plugin-foo-0.1.0-x86_64-pc-windows-msvc.toml
```

The repository URL comes from the crate's `repository` field on crates.io — at that point
the plugin is not installed yet, so the registry is the only thing that can be asked.

## Where the manifest comes from

The plugin crate ships `<manifest_name>` at its source root. During a build-host install,
this crate locates the crate source through `cargo metadata` and copies the file into the
install directory:

```text
cargo metadata --format-version 1 --manifest-path <wrapper>/Cargo.toml
  → find the entry in packages[] whose name matches the plugin crate
  → take the parent of its manifest_path — that is the crate source directory
  → copy <manifest_name> from there
```

This keeps a single source of truth: a plugin's metadata travels with its code. And detection
at runtime stays a plain file read — **no `dlopen` is needed just to list plugins**.

## What it does not do

- **No ABI validation.** It has no idea what is inside `T`. Checking `abi_version` is the host
  contract crate's job.
- **No `catch_unwind` call sites.** A helper is provided (`panic::guard`), but the contract
  crate is what knows *which* calls cross the boundary, so *it* must wrap them.
- **No async.** Installing starts a `cargo build`; loading is `dlopen`. Both are synchronous.
- **No source restrictions.** No allowlist, no signature checks, no sandbox — the same trust
  model as `cargo install`.

The dividing line is one question: **does the operation need to know what is inside `T`?**

| Operation | Needs `T`'s contents? | Owner |
| --- | --- | --- |
| install / uninstall / list | no | this crate |
| `dlopen`, look up the symbol, cast to `*const T` | no | this crate |
| query crates.io | no | this crate |
| validate `abi_version` | **yes** | contract crate |
| call `command()` / `name()` | **yes** | contract crate |
| manage cross-boundary string lifetimes | **yes** | contract crate |

## Development

```text
crate-plugin-kit/
├── Cargo.toml            # [package] + single-element [workspace]
├── build.rs              # injects the target triple
├── docs/proposal.md      # design notes
├── src/
│   ├── lib.rs            # public exports + crate docs
│   ├── config.rs         # KitConfig / KitPaths
│   ├── error.rs          # KitError
│   ├── manifest.rs       # manifest schema + read/write
│   ├── store.rs          # CratePluginKit<T>
│   ├── loader.rs         # generic dlopen, no type erasure
│   ├── lock.rs           # cross-process file lock
│   ├── cache.rs          # .plugins.json
│   ├── registry.rs       # crates.io queries
│   ├── panic.rs          # catch_unwind helper
│   └── install/
│       ├── build_host.rs # generated wrapper + cargo build (default)
│       └── prebuilt.rs   # GitHub Releases download (accelerator)
└── tests/
    ├── load.rs           # end-to-end: build a cdylib, dlopen it, call across
    └── fixtures/toy-plugin/   # the zero-dependency cdylib used by that test
```

```bash
cargo fmt --all --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked
cargo package --locked
```

`tests/load.rs` is the one that matters most: it compiles the fixture into a real
`cdylib`, copies it into a temporary plugin store, then `dlopen`s it and calls a function
pointer across the boundary. Everything else is file I/O and string derivation.

### On `rust-toolchain.toml`

There deliberately isn't one. Two reasons:

1. A pinned channel would override the CI job that tests the MSRV, which is the thing
   `rust-version` in `Cargo.toml` actually promises;
2. pinning an exact version forces contributors to download a whole extra toolchain,
   while `rust-version` plus CI already covers the real problem.

The generated wrapper does not get one either — it inherits whatever toolchain you are
already using.

## Repository

<https://github.com/imba97/crate-plugin-kit>

## License

MIT — see [LICENSE](LICENSE).