crab/README.md

# CRAB (Crimean RAC Bundle)

CRAB is a Java client and server implementation of the RAC (Real Address Chat) protocol, designed to facilitate communication in a lightweight and efficient manner.

## Table of Contents

- [Overview](#overview)
- [Installation](#installation)
- [Usage](#usage)
- [RAC Protocol](#rac-protocol)

## Overview

CRAB aims to provide a simple and effective implementation of the RAC protocol, which is humorously referred to as Mr. Sugoma’s “IRC killer.” The protocol allows clients to send messages to a server, which processes them according to predefined message types.

## Installation

To get started with CRAB, follow these steps:

1. **Clone the repository:**
   ```bash
   git clone https://gitea.bedohswe.eu.org/pixtaded/crab.git
   cd crab
   ```

2. **Build the project:**
   Ensure you have Java Development Kit (JDK) of version 17 or higher installed. You can build the project using Gradle:
   ```bash
   ./gradlew clean build
   ```

3. **Run the bundle**: You will have the built .jar package in ./build/libs directory.

## Usage

Once the server is running, clients can connect to it and send messages according to the RAC protocol. The client will need to specify the server's address and port to establish a connection.

## RAC Protocol

1. Message Retrieval

   a. The client initiates a message retrieval session by sending the byte `0x00` to the server.

   b. In response, the server transmits the size of the available messages as an ASCII-encoded string.

   c. After receiving the size, the client must send one of the following bytes or close the connection:

   i. Sending `0x01` instructs the server to transmit all messages in full.

   ii. Sending `0x02` followed by the client’s cached messages length (as an ASCII string, e.g., `0x02"1024"`) instructs the server to transmit only new messages added since the cached length. The server sends messages starting from the cached length offset, and the client updates its cached length to the total size received in step 1b after processing the new messages.

2. Message Transmission

   a. To send a message, the client issues a request in one of the following formats:

   i. Unauthenticated Message: The client sends the byte `0x01` followed immediately by the message content. The server does not send a response.

   ii. Authenticated Message: The client sends the byte `0x02` followed by the username, a newline character (`\n`), the password, a newline character and the message content. The server responds with a single byte:
   - `0x01` indicates the user does not exist.
   - `0x02` indicates the password is incorrect.
   - A successful authentication results in the server accepting the message without sending a response.

3. User Registration

   a. To register a new user, the client sends a request formatted as:
   - The byte `0x03`.
   - The username, followed by a newline character (`\n`).
   - The password.

   b. The server processes the request and responds with a single byte:
   - `0x01` if the username already exists.
   - A successful registration is assumed if no error byte (`0x01`) is received. The client should close the connection after handling the response.

### Additional Notes:

- The current specification of RACv2 is implemented in `lRACd` version 2.0.0 and `clRAC` version 2.0.0.

- When using `0x02` for incremental retrieval, the client must ensure the cached length is synchronized with the server’s total message length (retrieved via `0x00`). The server sends messages from the cached length onward, and the client calculates the read size as `(total_length - cached_length)`.

- After receiving incremental messages, the client must update its cached length to the total length provided in step 1b to maintain consistency in subsequent requests.

- For authenticated message transmission (`0x02`) or user registration (`0x03`), the client must follow the specified format precisely. The server validates the structure of the request and responds with error codes only for specific failure conditions (e.g., invalid credentials or duplicate usernames).