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 the following format:

   `0x01` followed immediately by the message content.

### Additional Notes:

- Although the protocol may appear similar to RACv1, it is important to note that RACv1.99 represents the beta development phase of RACv2. Consequently, significant changes and enhancements are anticipated. The current specification is implemented in `lRACd` version 1.99.2 and `clRAC` version 1.99.2.

- 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.