hi

Hi - MQTT Chat Client

📌 Overview

Hi is a terminal-based MQTT chat room that combines the MQTT protocol with Charmbracelet Bubbles to create a beautiful and interactive CLI chat tool.

🚀 Installation

Method 1: Using Go Install

go install github.com/longkeyy/hi@latest

Method 2: Using Homebrew (macOS/Linux)

brew install hi

Method 3: Using Package Managers

Debian/Ubuntu (.deb):

# Download from GitHub Releases
wget https://github.com/longkeyy/hi/releases/download/vX.X.X/hi_X.X.X_linux_amd64.deb
sudo dpkg -i hi_X.X.X_linux_amd64.deb

Fedora/RHEL/CentOS (.rpm):

# Download from GitHub Releases
wget https://github.com/longkeyy/hi/releases/download/vX.X.X/hi_X.X.X_linux_amd64.rpm
sudo rpm -i hi_X.X.X_linux_amd64.rpm

Alpine (.apk):

# Download from GitHub Releases
wget https://github.com/longkeyy/hi/releases/download/vX.X.X/hi_X.X.X_linux_amd64.apk
sudo apk add --allow-untrusted hi_X.X.X_linux_amd64.apk

Method 4: Build from Source

git clone https://github.com/longkeyy/hi.git
cd hi
go build -o hi

💡 Usage

# Use default parameters (username Bell-xxxx, room hi)
hi

# Specify username and room
hi --name alice --room lobby

# Specify MQTT broker
hi --host mqtt://broker.hivemq.com:1883 --name bob

# Show version
hi --version

🎯 Features

📁 Project Structure

hi/
├── go.mod                          # Go module file
├── cmd/hi/main.go                  # CLI entry point
├── hi.go                           # Core package API (extensible)
├── mqtt.go                         # MQTT client (locked)
├── model.go                        # TUI model
├── styles.go                       # Style definitions
├── utils.go                        # Utility functions
├── examples/                       # Example projects
│   ├── headless/                   # Headless mode example
│   ├── with_keyword_replace/       # Keyword filter example
│   └── plugins/                    # Example middleware plugins
└── README.md                       # Project documentation

🔌 Extensibility

The Hi package provides middleware hooks for customizing message processing:

MessageMiddleware Interface

type MessageMiddleware interface {
    // ProcessIncoming processes received messages before displaying
    ProcessIncoming(sender, content string) (string, bool)

    // ProcessOutgoing processes messages before sending
    ProcessOutgoing(content string) (string, bool)
}

Locked Components (Cannot be modified)

• ❌ Topic structure: chatroom/<room>/<user> (locked)
• ❌ Username format: Must end with -XXXX (4 digits, locked)
• ❌ MQTT connection logic (locked)

Extensible Components (Can be customized)

• ✅ Message processing before sending
• ✅ Message processing after receiving
• ✅ Keyword filtering/replacement
• ✅ Encryption/Decryption (for internal development)
• ✅ Custom message handlers

💻 Development Examples

Example 1: Basic CLI Usage

package main

import (
    "log"
    "github.com/longkeyy/hi"
)

func main() {
    config := hi.Config{
        Host:     "mqtt://test.mosquitto.org:1883",
        Username: "alice",
        Room:     "lobby",
    }

    client, err := hi.NewClient(config)
    if err != nil {
        log.Fatal(err)
    }

    if err := client.Run(); err != nil {
        log.Fatal(err)
    }
}

Example 2: Keyword Filtering

package main

import (
    "log"
    "github.com/longkeyy/hi"
    "github.com/longkeyy/hi/examples/plugins"
)

func main() {
    // Create keyword replacer
    replacer := plugins.NewKeywordReplacer(map[string]string{
        "bad":   "***",
        "ugly":  "***",
    })

    config := hi.Config{
        Host:       "mqtt://test.mosquitto.org:1883",
        Username:   "alice",
        Room:       "lobby",
        Middleware: []hi.MessageMiddleware{replacer},
    }

    client, err := hi.NewClient(config)
    if err != nil {
        log.Fatal(err)
    }

    client.Run()
}

Example 3: Headless Mode (No TUI)

package main

import (
    "fmt"
    "log"
    "github.com/longkeyy/hi"
)

func main() {
    config := hi.Config{
        Host:     "mqtt://test.mosquitto.org:1883",
        Username: "bot",
        Room:     "lobby",
    }

    client, err := hi.NewClient(config)
    if err != nil {
        log.Fatal(err)
    }

    // Run without TUI
    err = client.RunHeadless(func(sender, content string) {
        fmt.Printf("[%s]: %s\n", sender, content)
    })

    if err != nil {
        log.Fatal(err)
    }

    // Send messages programmatically
    client.SendMessage("Hello from bot!")
}

Example 4: Custom Encryption Middleware (Internal)

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "encoding/base64"
    "github.com/longkeyy/hi"
)

type EncryptionMiddleware struct {
    cipher cipher.Block
}

func (e *EncryptionMiddleware) ProcessIncoming(sender, content string) (string, bool) {
    // Decrypt received messages
    decrypted, _ := decrypt(e.cipher, content)
    return decrypted, true
}

func (e *EncryptionMiddleware) ProcessOutgoing(content string) (string, bool) {
    // Encrypt before sending
    encrypted, _ := encrypt(e.cipher, content)
    return encrypted, true
}

func main() {
    key := []byte("my-secret-key-32") // 32 bytes for AES-256
    cipher, _ := aes.NewCipher(key)

    config := hi.Config{
        Host:       "mqtt://test.mosquitto.org:1883",
        Username:   "secure-user",
        Room:       "secure-room",
        Middleware: []hi.MessageMiddleware{
            &EncryptionMiddleware{cipher: cipher},
        },
    }

    client, _ := hi.NewClient(config)
    client.Run()
}

⚙️ Configuration

🔀 MQTT Topic Structure

MQTT uses the following topic model for chat communication:

chatroom/<room>/<user>

• All users subscribe to: chatroom/<room>/#
• Each user publishes to: chatroom/<room>/<your_name>

Example:

• chatroom/room1/alice
• chatroom/room1/bob

The sender can be extracted from msg.Topic().

🎨 UI Design (Bubbles + Lipgloss)

Layout

╔═══════════════════════════════╗
║         MQTT Chat Room       ║ <- Status bar (optional)
╠═══════════════════════════════╣
║ 💬 alice: Hello!              ║ <- Message history
║ 💬 bob: Hi there~             ║
║ 💬 me: OK let's go            ║ <- Your messages (green/right-aligned)
║ ...                          ║
╠═══════════════════════════════╣
║ > Type message here...       ║ <- textinput.Model
╚═══════════════════════════════╝

UI Features

📦 Dependencies

github.com/charmbracelet/bubbletea
github.com/charmbracelet/bubbles
github.com/charmbracelet/lipgloss
github.com/eclipse/paho.mqtt.golang

🔄 Message Flow

sequenceDiagram
    participant User as Your Terminal
    participant MQTT as MQTT Broker
    participant Other as Other Users

    User->>MQTT: CONNECT to mqtt.eclipse.org
    User->>MQTT: SUBSCRIBE chatroom/room1/#
    loop Chat loop
        User->>MQTT: PUBLISH chatroom/room1/<name> with msg
        MQTT-->>Other: DELIVER msg via chatroom/room1/<name>
        MQTT-->>User: ECHO msg (if subscribed)
    end

🚢 Publishing to Homebrew

After creating a GitHub release with version tag (e.g., v1.0.0):

1. Download the release checksums from GitHub
2. Update homebrew-formula/hi.rb with:
   • Version number
   • SHA256 checksums for each platform
3. Submit a PR to homebrew-core
4. Follow the Homebrew Formula Cookbook

📝 License

MIT