Metadata-Version: 2.5
Name: dikolab-horde-ipc
Version: 0.0.2
Summary: The JSON-RPC protocol library shared by horde and every horde plugin.
Project-URL: Homepage, https://diko316.gitlab.io/dikolab-horde/
Project-URL: Documentation, https://diko316.gitlab.io/dikolab-horde/
Project-URL: Funding, https://paypal.me/dikolab
Author-email: Diko TechSlave <diko316@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: horde,ipc,json-rpc,plugin,protocol,stdio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: dikolab-horde-common>=0.0.2
Description-Content-Type: text/markdown

<img src="https://diko316.gitlab.io/dikolab-horde/assets/horde-logo.png" alt="horde" width="140">

# dikolab-horde-ipc

**The JSON-RPC 2.0 protocol shared by horde and every horde plugin.** It defines
the methods, validates message shapes, and hands the other side typed objects —
a frame that does not match its declared shape raises where it is decoded, never
as a `KeyError` three layers further in.

**It performs no effects.** `fs.write` is a shape here; only horde writes a file.

Install this if you are implementing one side of the protocol by hand. Most
plugin authors want [dikolab-horde-sdk](https://pypi.org/project/dikolab-horde-sdk/),
which does this for you.

> **Status: alpha.** `0.0.2` ships the complete protocol — twenty methods across
> five namespaces, the transport, and `Peer`. `plugin.cleanup` is the twentieth,
> new in this release. The interfaces may still move.

## Prerequisites

- Python 3.11 or newer
- One dependency, [dikolab-horde-common](https://pypi.org/project/dikolab-horde-common/)

## Getting started

```sh
pip install dikolab-horde-ipc
```

Claim `stdout` before anything else — the protocol owns it, and a stray
`print()` would desynchronise the connection — then send a request:

```python
import sys

from dikolab_horde_ipc_shared import FsReadParams, Method, Peer, protect_stdout

protocol_out = protect_stdout()
peer = Peer(sys.stdin.buffer, protocol_out)

request_id = peer.send_request(Method.FS_READ, FsReadParams(paths=["pyproject.toml"]))
result = peer.wait_for(request_id)
```

`wait_for` keeps pumping the connection while it blocks, so requests arriving the
other way are still dispatched.

### Twenty methods, five namespaces

| Namespace | Methods |
|---|---|
| `fs.` | `read` `write` `delete` `list` `mkdir` `move` `symlink` |
| `exec.` | `run` `cancel` `started` `chunk` |
| `tty.` | `print` `trace` `prompt` |
| `plugin.` | `initialize` `help` `cleanup` |
| `process.` | `start` `end` `interrupt` |

Namespaces group by **subject, not direction** — `plugin.` and `process.` each
carry messages both ways. `Method` is a `StrEnum`, so a member compares equal to
its wire string. `PLUGIN_METHODS` is the fifteen a plugin may send; the other
five are horde's.

**The protocol reference and API examples:**
https://diko316.gitlab.io/dikolab-horde/authoring/protocol/

## Documentation

- [The protocol](https://diko316.gitlab.io/dikolab-horde/authoring/protocol/) — what each method is for
- [API reference](https://diko316.gitlab.io/dikolab-horde/dikolab-horde-ipc/api/) — with runnable [examples](https://diko316.gitlab.io/dikolab-horde/dikolab-horde-ipc/api/examples/)
- [Manual](https://diko316.gitlab.io/dikolab-horde/dikolab-horde-ipc/manual/) · [Release notes](https://diko316.gitlab.io/dikolab-horde/dikolab-horde-ipc/release-notes/)

## Support

If horde saves you time, you can support its development:
https://paypal.me/dikolab

---

© 2025–2026 dikolab. Released under the MIT License.
