hoy 0.3.0

Real-time messaging TUI app
Documentation

Hoy! - TUI real-time messaging app

crates.io docs.rs pre-commit pipeline status Coverage Status

A TUI real time messaging app inspired by accord.

Index

Installation

Install using cargo:

cargo install hoy

Usage

Both the server and client currently share the same binary hoy:

Usage: hoy [OPTIONS]

Options:
  -s, --server               Run in server mode instead of client mode
  -p, --port <PORT>          Port to bind the server or connect the client to [default: 7777]
  -a, --address <IPV4>       Server address to connect to. [default: localhost]
  -u, --username <USERNAME>  Client username (required in client mode)
  -d, --db <FILE>            Path to storage db file [default: ~/.local/share/hoy/hoy.db]
  -i, --incognito            Run server with a temporary storage instead of a persistent db storage
  -n, --no-tui               Run client with a simple stdout UI instead of TUI
  -h, --help                 Print help
  -V, --version              Print version

Starting the server

Run in server mode with the -s flag. The default port is 7777.

# Start on default port 7777
hoy -s

# Start on a custom port
hoy -s -p 9000

Connecting a client

Connect as a client by providing a username with -u. The client connects to 127.0.0.1 on the specified port (default 7777).

# Connect with username "alice" to default port
hoy -u alice

# Connect to a custom port
hoy -u alice -p 9000

On connection, the server places the client in #general and broadcasts a join message to all connected clients.

Chat commands

Once connected, type in the terminal. Plain text sends a chat message. Special commands begin with /:

Command Action
/list Requests a list of available rooms
/room <room name> Requests joining/creating a room
/ping Send a heartbeat ping; server replies Pong.
/disconnect Disconnect from the server without exiting.
/quit Disconnect and exit the client.
/exit Alias for /quit.

Any other input is sent as a chat message and broadcast to all clients in the room.

Valid room name:

  • Allowed characters: lowercase ASCII letters, Ascii digits, _, -
  • Length: 1-64 characters.

Crates

  1. hoy-core - Shared domain logic
  2. hoy-net - Networking layer
  3. hoy-protocol - Wire level protocol defining packets and codec
  4. hoy-tui - App TUI

Protocol

The wire protocol is useful for contributors or anyone building alternative clients.

Frame format

Each packet is encoded as a length-prefixed frame:

[4 bytes: big-endian u32 payload length][N bytes: JSON payload]

The JSON payload is a serialized ClientPacket or ServerPacket enum value. There is no framing delimiter; frames are concatenated directly in the TCP stream.

Client packets and server packets

See hoy-protocol readme.

Similar projects

License

This project is licensed under either of:

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed under the Apache-2.0 and MIT license, without any additional terms or conditions.

Development

See contribution guidelines.

TLDR:

Requires just to bootstrap all tools and configuration

cargo install just
just init # setup repo, install hooks and all required tools

To run:

just run

To test:

just test

Before committing work:

just pre-commit

To see all available commands:

just list