88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
# Building & running
|
|
|
|
## Prerequisites
|
|
|
|
- A stable **Rust** toolchain (`cargo`, `rustc`).
|
|
- **OpenSSL** development headers for the default TLS backend (the `openssl` crate
|
|
links against the system library) — e.g. `libssl-dev` on Debian/Ubuntu. The
|
|
optional pure-Rust rustls backend (`tls_backend = rustls`) needs no system
|
|
library.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
git clone https://git.devtronic.pro/fedserv/echoIRCd
|
|
cd echoIRCd
|
|
|
|
# development build (fast to compile, slow to run)
|
|
cargo build
|
|
|
|
# release build — ALWAYS use this in production; the debug build is unoptimized
|
|
# and far slower on the CPU-bound paths (TLS, hashing, cloaking, line parsing)
|
|
cargo build --release
|
|
```
|
|
|
|
The binaries land in `target/debug/echoircd` and `target/release/echoircd`.
|
|
|
|
## Run
|
|
|
|
echoircd takes one argument, the path to a config file (default `./echoircd.conf`):
|
|
|
|
```sh
|
|
cp echoircd.conf.example echoircd.conf # then edit: oper pass, cloak_key, TLS paths
|
|
cargo run --release # reads ./echoircd.conf
|
|
# or run the binary directly:
|
|
./target/release/echoircd /path/to/echoircd.conf
|
|
```
|
|
|
|
Point a client at it: `/server 127.0.0.1 6667`, or `6697` for TLS once a
|
|
certificate is configured. See [configuration](configuration.md) for every
|
|
setting and [deployment](deployment.md) for running it as a supervised service.
|
|
|
|
> Your live `echoircd.conf` is gitignored on purpose — it holds secrets (oper
|
|
> password, cloak key, link password). Never commit it.
|
|
|
|
## Tests
|
|
|
|
```sh
|
|
cargo test # unit + integration tests
|
|
cargo test --test integration # just the end-to-end suite
|
|
```
|
|
|
|
The integration suite spawns the real binary on ephemeral ports and drives it as
|
|
a client — covering reactor-pool cross-worker delivery, TLS-in-reactor handshakes,
|
|
the stalled-handshake reap, the accept-rate limiter, and nick collisions. It
|
|
tracks and kills its child processes by PID, never by name. The parser and the S2S
|
|
convergence logic also carry property-based (`proptest`) suites.
|
|
|
|
## Project layout
|
|
|
|
```text
|
|
src/
|
|
main.rs startup: config, listeners, the reactor pool, the core thread
|
|
ircd.rs the core event loop and event types
|
|
server.rs the Server: all state, plus helpers (send, snotice, off-core work)
|
|
socketengine.rs the I/O edge: reactor pool, acceptor, TLS-in-reactor, links
|
|
tls.rs the TLS backend (OpenSSL) — blocking + non-blocking sessions
|
|
channels.rs Channel, membership, and the channel mode struct
|
|
users.rs User and session state
|
|
mode.rs ChanMode / UserMode traits and the mode registry
|
|
command.rs the Command trait
|
|
module.rs the module lifecycle-hook trait
|
|
coremods/ built-in commands (registration, channels, messaging, oper, …)
|
|
modules/ optional, pluggable modules (70+ of them)
|
|
tests/ end-to-end integration tests
|
|
deploy/ production systemd units + firewall script
|
|
docs/ this manual
|
|
```
|
|
|
|
## Extending
|
|
|
|
Three extension points, each one file plus one table entry:
|
|
|
|
- **Commands** (`src/command.rs`, `src/coremods/`) — a handler with `name`,
|
|
`min_params`, `before_reg`, and `handle(&mut Server, uid, params)`.
|
|
- **Modes** (`src/mode.rs`) — channel/user modes as `ChanMode` / `UserMode`
|
|
handler objects; adding one never touches the parser.
|
|
- **Modules** (`src/module.rs`, `src/modules/`) — lifecycle hooks; pre-hooks can
|
|
**Deny** a register/command/message, notify-hooks fire after.
|