koi-embedded 0.4.1

Embed local network discovery, DNS, health, and TLS directly in your Rust application
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# koi-embedded

[![Crates.io](https://img.shields.io/crates/v/koi-embedded.svg)](https://crates.io/crates/koi-embedded)
[![Docs.rs](https://docs.rs/koi-embedded/badge.svg)](https://docs.rs/koi-embedded)
[![License](https://img.shields.io/crates/l/koi-embedded.svg)](https://github.com/sylin-org/koi#license)

Embed local network discovery, DNS, health, and TLS directly in your Rust application.

## Overview

`koi-embedded` lets you embed the full Koi stack — mDNS discovery, DNS
resolution, health monitoring, TLS proxy, certmesh, and UDP bridging — inside
your own Rust application. It provides a `Builder` for configuration and
returns typed handles (`MdnsHandle`, `DnsHandle`, `HealthHandle`, etc.) for
interacting with each capability, plus a `KoiEvent` broadcast stream for
reacting to system-wide events.

## Usage

```rust
use koi_embedded::{Builder, RegisterPayload};

// Build the embedded stack, then start it. `build()` is sync and returns a
// `KoiEmbedded`; `start()` is async and returns the running `KoiHandle`.
let koi = Builder::new()
    .mdns(true)
    .build()?
    .start()
    .await?;

// Register a service through the mDNS handle (`mdns()` returns a `Result`;
// `register` is synchronous).
koi.mdns()?.register(RegisterPayload {
    name: "My Service".to_string(),
    service_type: "_http._tcp".to_string(),
    port: 8080,
    ip: None,
    lease_secs: None,
    txt: Default::default(),
})?;

// Subscribe to the system-wide event stream.
let mut rx = koi.subscribe();
while let Ok(event) = rx.recv().await {
    println!("{event:?}");
}
```

## Cargo features (lean builds)

Three heavy, version-locking backends are gated behind **default-on** features. A default
dependency is unchanged; a lean consumer opts out, and re-arms à la carte:

| Feature | Default | Compiles in | Off → fallback |
| --- | --- | --- | --- |
| `docker` | on | `bollard` Docker/Podman client (`=`-pinned stubs) | runtime backend → `BackendUnavailable` |
| `keyring` | on | OS keychain / Secret Service / D-Bus | vault uses its passphrase backend |
| `qr` | on | `qrcode` + `image` PNG codec | enrollment returns the `otpauth://` URI text |

```toml
# default — everything
koi-embedded = "0.4"
# lean — no bollard, no OS-keychain/D-Bus, no image codec
koi-embedded = { version = "0.4", default-features = false }
# à la carte (also: features = ["full"])
koi-embedded = { version = "0.4", default-features = false, features = ["docker"] }
```

These are compile-time choices, distinct from the runtime capability toggles on
`Builder` (which compile everything and just don't start it). See the
[embedded guide](https://github.com/sylin-org/koi/blob/main/docs/guides/embedded.md)
and [ADR-014](https://github.com/sylin-org/koi/blob/main/docs/adr/014-optional-backend-features.md).

## Part of Koi

This crate is part of the [Koi](https://github.com/sylin-org/koi) workspace.
See the main repository for architecture details and the full crate inventory.

## License

Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
[MIT License](LICENSE-MIT) at your option.