### Local Development Setup for FractalBits

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Guides users through setting up and running FractalBits services locally. Covers cloning the repository, initializing the project, building all components, initializing and starting services, checking their status, viewing logs, stopping services, and running compatibility or full test suites.

```bash
# Clone and build
git clone https://github.com/fractalbits-labs/fractalbits-main.git
cd fractalbits-main

# Initialize repository
just repo init

# Build all components (API Server, BSS, NSS, RSS)
just build
# Alternatively: cargo xtask build

# Initialize service configuration
just service init

# Start all services with systemd user units
just service start

# Check service status
just service status
systemctl --user status api_server
systemctl --user status bss_server
systemctl --user status nss_server
systemctl --user status rss_server

# View service logs
journalctl --user -u api_server -f
journalctl --user -u bss_server -f

# Stop all services
just service stop

# Run S3 API compatibility tests
just precheckin --s3-api-only

# Run full test suite with unit tests
just precheckin
```

--------------------------------

### Local Development Setup

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Instructions for setting up and running FractalBits services locally, including building, initialization, and management.

```APIDOC
## Local Development Setup

### Description
This guide outlines the steps required to clone, build, initialize, and manage FractalBits services on a local development environment.

### Method
CLI Commands (git, just, systemctl, journalctl)

### Endpoint
N/A (Local commands)

### Parameters
N/A

### Request Example
```bash
# Clone the repository
git clone https://github.com/fractalbits-labs/fractalbits-main.git
cd fractalbits-main

# Initialize the repository
just repo init

# Build all components (API Server, BSS, NSS, RSS)
just build
# Alternatively, use: cargo xtask build

# Initialize service configuration
just service init

# Start all services using systemd user units
just service start

# Check the status of services
just service status
systemctl --user status api_server
systemctl --user status bss_server
systemctl --user status nss_server
systemctl --user status rss_server

# View service logs in real-time
journalctl --user -u api_server -f
journalctl --user -u bss_server -f

# Stop all services
just service stop

# Run S3 API compatibility tests only
just precheckin --s3-api-only

# Run the full test suite including unit tests
just precheckin
```

### Response
#### Success Response (CLI Output)
Commands execute and provide output indicating success or status. For example, `just build` will compile the code, and `just service status` will show if services are active.

#### Response Example
```
# Example output for 'just build':
Compiling fractalbits-main v0.1.0 (/path/to/fractalbits-main)
Finished release [optimized] target(s) in Xs

# Example output for 'systemctl --user status api_server':
● api_server.service - API Server
     Loaded: loaded (/etc/systemd/user/api_server.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2023-10-27 11:00:00 UTC; 1h ago
   Main PID: 12345 (api_server)
      Tasks: 10
   Memory: 50.0M
      CPU: 1min 30s
     CGroup: ...

Oct 27 11:00:00 hostname systemd[1111]: Started API Server.
```
```

--------------------------------

### Docker Deployment

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Guides for building and running FractalBits services using Docker for testing and development.

```APIDOC
## Docker Deployment

### Description
This section provides instructions for building FractalBits Docker images and running containers for development and testing purposes.

### Method
CLI Commands (`just`, `docker`)

### Endpoint
N/A (Docker commands)

### Parameters
#### `just` Docker Commands
- `docker build` - Builds the Docker image.
  - `--release` - Optional flag to build a release (production) image.
- `docker run` - Runs a Docker container.
  - `--port` (integer) - Optional - Maps a host port to the container's port (default 8080).
  - `--detach` - Optional flag to run the container in detached mode (background).
  - `--name` (string) - Optional - Assigns a name to the container.
- `docker logs` - Views container logs.
  - `--name` (string) - Required - The name of the container.
  - `--follow` - Optional flag to follow log output in real-time.
- `docker stop` - Stops a running container.
  - `--name` (string) - Required - The name of the container.

#### Direct `docker run` Command
- `--rm` - Automatically remove the container when it exits.
- `--privileged` - Required for `io_uring` support (check specific FractalBits requirements).
- `-p` (host_port:container_port) - Maps host port to container port.
- `image_name:tag` - Specifies the Docker image to run (e.g., `ghcr.io/fractalbits-labs/fractalbits-main:latest`).

### Request Example
```bash
# Build Docker image (debug build)
just docker build

# Build release Docker image for production
just docker build --release

# Run container in foreground (default port 8080)
just docker run

# Run container with custom port mapping
just docker run --port 9080

# Run container in background with a specific name
just docker run --detach --name fractalbits-dev

# View container logs, following output
just docker logs --name fractalbits-dev --follow

# Stop a running container
just docker stop --name fractalbits-dev

# Using Docker directly (requires --privileged for io_uring)
docker run --rm --privileged -p 8080:8080 \
    ghcr.io/fractalbits-labs/fractalbits-main:latest
```

### Response
#### Success Response (CLI Output)
Docker commands provide output indicating the success of the operation, such as container creation, log streaming, or status updates.

#### Response Example
```
# Example output for 'just docker run --detach --name fractalbits-dev':
Container fractalbits-dev started.

# Example output for 'just docker logs --name fractalbits-dev --follow':
[INFO] Starting FractalBits API Server...
[INFO] API Server listening on 0.0.0.0:8080
...
```
```

--------------------------------

### Run FractalBits Services Locally with 'just'

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

This snippet shows how to initialize the service configuration and start all FractalBits services (API, BSS, NSS, RSS) locally using the 'just' command runner. It also includes commands to check the status of these services.

```bash
# Initialize service configuration
just service init

# Start all services (API, BSS, NSS, RSS)
just service start

# Check service status
just service status

# Check service with normal systemd commands
systemctl --user status api_server
journalctl --user -u api_server
```

--------------------------------

### List S3 Objects with Delimiter and Recursively

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Demonstrates how to list objects in an S3 bucket. The first example uses `list-objects-v2` with a delimiter to simulate directory structures, returning common prefixes for subdirectories. The second example uses `aws s3 ls --recursive` to list all objects within a bucket recursively.

```bash
aws s3api list-objects-v2 \
    --bucket my-bucket \
    --prefix "images/" \
    --delimiter "/"
```

```bash
aws s3 ls s3://my-bucket --recursive
```

--------------------------------

### AWS Deployment with FractalBits CDK

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

These commands demonstrate deploying FractalBits to AWS using the CDK. They cover installing cross-compilation tools, building binaries, uploading them to S3, creating VPCs with different templates (mini and perf_demo), describing the deployed stack, accessing instances via SSM, running benchmark workloads, and destroying the deployed resources.

```bash
# Install cross-compilation tool (optional, for custom builds)
cargo install --locked cargo-zigbuild

# Build binaries for AWS deployment
just deploy build

# Upload binaries to S3 builds bucket
just deploy upload

# Deploy with mini template (1 instance per service type)
just deploy create-vpc --template mini

# Deploy with perf_demo template (14 API servers, 6 BSS nodes, benchmark clients)
just deploy create-vpc --template perf_demo --with-bench

# View deployed infrastructure details
just describe-stack

# Log into EC2 instance via SSM
aws ssm start-session --target i-0dc3f71d451869872

# Run benchmark workload (if deployed with --with-bench)
# Log into bench_server instance first
WORKLOAD=get_4k /opt/fractalbits/bin/bench_start.sh

# Destroy VPC and all resources (requires confirmation)
just deploy destroy-vpc
```

--------------------------------

### Deploy FractalBits to AWS

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Guides on deploying FractalBits to AWS, including uploading built binaries, creating VPC infrastructure, and describing the deployed stack. Assumes AWS CLI configuration is set up. Uses `just deploy` commands.

```bash
# Upload your binaries to S3 builds bucket
just deploy upload

# Deploy with perf_demo template (14 API servers, 42 bench clients, 6 BSS nodes)
# or use "mini" template, which includes a single instance for each node type.
# See more options in the command help.
just deploy create-vpc --template perf_demo --with-bench

# View deployed stack information
just describe-stack
```

--------------------------------

### Start SSM Session to RSS Instance (Bash)

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/docs/API_KEY_MANAGEMENT.md

Initiates an AWS Systems Manager (SSM) session to a specified EC2 instance. This requires the Instance ID of the target RSS instance, which is obtained from the `describe-stack` command.

```bash
ec2=<RSS_INSTANCE_ID>
aws ssm start-session --target=$ec2
```

```bash
ec2=i-0b97a853c3e223dc0
aws ssm start-session --target=$ec2
```

--------------------------------

### Get Help for rss_admin API Key Commands (Bash)

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/docs/API_KEY_MANAGEMENT.md

Displays the help menu for `rss_admin`'s API key management subcommands, providing information on available operations.

```bash
/opt/fractalbits/bin/rss_admin --rss-addr=localhost:8088 api-key --help
```

--------------------------------

### S3 API List Operations with AWS CLI

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Demonstrates how to list objects within a bucket using the AWS CLI, including support for version 1 and version 2 of the ListObjects API. Examples show prefix filtering and pagination using continuation tokens for efficient retrieval of large numbers of objects.

```bash
# ListObjects (v1) - List objects in bucket
aws s3api list-objects --bucket my-bucket --prefix "logs/"

# ListObjectsV2 - Enhanced listing with continuation tokens
aws s3api list-objects-v2 \
    --bucket my-bucket \
    --prefix "data/" \
    --max-keys 100 \
    --start-after "data/file-100.txt"
# Returns: Contents[], NextContinuationToken for pagination
```

--------------------------------

### S3 API Bucket Operations with AWS CLI

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Provides examples of managing S3 buckets using the AWS CLI, covering creation, checking existence, listing all buckets, and deletion. These operations are fundamental for organizing data storage within the FractalBits system.

```bash
# CreateBucket - Create a new bucket
aws s3 mb s3://my-bucket

# HeadBucket - Check if bucket exists
aws s3api head-bucket --bucket my-bucket
# Returns HTTP 200 if exists, 404 if not

# ListBuckets - List all buckets
aws s3 ls
# Output: 2025-12-19 10:30:45 my-bucket

# DeleteBucket - Delete an empty bucket
aws s3 rb s3://my-bucket
```

--------------------------------

### Programmatic API Usage with FractalBits (Python)

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

This Python code snippet showcases integration with FractalBits using the boto3 SDK. It covers essential operations such as creating buckets, uploading and downloading objects, managing multipart uploads for large files, and listing objects with pagination. Ensure 'boto3' is installed.

```python
import boto3
from botocore.client import Config

# Configure boto3 client for FractalBits
s3_client = boto3.client(
    's3',
    endpoint_url='http://localhost:8080',
    aws_access_key_id='test_api_key',
    aws_secret_access_key='test_api_secret',
    region_name='localdev',
    config=Config(signature_version='s3v4')
)

# Create bucket
s3_client.create_bucket(Bucket='my-bucket')

# Upload object
with open('data.txt', 'rb') as f:
    s3_client.put_object(
        Bucket='my-bucket',
        Key='data.txt',
        Body=f,
        ContentType='text/plain'
    )

# Download object
response = s3_client.get_object(Bucket='my-bucket', Key='data.txt')
data = response['Body'].read()
print(f"Downloaded {len(data)} bytes")

# Multipart upload for large files
multipart_upload = s3_client.create_multipart_upload(
    Bucket='my-bucket',
    Key='large-file.bin'
)
upload_id = multipart_upload['UploadId']

# Upload parts (minimum 5MB each except last)
parts = []
with open('large-file.bin', 'rb') as f:
    part_number = 1
    while True:
        chunk = f.read(5 * 1024 * 1024)  # 5MB chunks
        if not chunk:
            break

        response = s3_client.upload_part(
            Bucket='my-bucket',
            Key='large-file.bin',
            UploadId=upload_id,
            PartNumber=part_number,
            Body=chunk
        )

        parts.append({
            'PartNumber': part_number,
            'ETag': response['ETag']
        })
        part_number += 1

# Complete multipart upload
s3_client.complete_multipart_upload(
    Bucket='my-bucket',
    Key='large-file.bin',
    UploadId=upload_id,
    MultipartUpload={'Parts': parts}
)

# List objects with pagination
paginator = s3_client.get_paginator('list_objects_v2')
for page in paginator.paginate(Bucket='my-bucket', Prefix='data/'):
    for obj in page.get('Contents', []):
        print(f"{obj['Key']} - {obj['Size']} bytes - {obj['LastModified']}")

```

--------------------------------

### FractalBits API Server Configuration

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

This TOML configuration file defines settings for the FractalBits API server. It includes network addresses for other services, port configurations for HTTP and HTTPS, worker thread settings, blob storage backend options (S3 hybrid or all in BSS), and rate limiting/retry configurations for S3 interactions. The example also shows how to load this configuration.

```toml
# api_server.toml - API Server configuration
nss_addr = "localhost:8086"
rss_addrs = ["localhost:8088"]
port = 8080
worker_threads = 8
core_affinity = true

[https]
enabled = true
port = 8443
cert_file = "data/etc/cert.pem"
key_file = "data/etc/key.pem"
force_http1_only = false

[blob_storage]
backend = "s3_hybrid_single_az"  # Options: s3_hybrid_single_az, s3_express_multi_az, all_in_bss_single_az

[blob_storage.s3_hybrid_single_az]
s3_region = "us-west-2"
s3_bucket = "my-data-bucket"
s3_endpoint_override = ""  # Optional custom S3 endpoint
blob_size_threshold = 1048576  # 1MB threshold for local vs S3 storage
local_bss_addrs = ["localhost:8084", "localhost:8085"]

[blob_storage.s3_hybrid_single_az.ratelimit]
enabled = true
put_qps = 7000   # PUT requests per second limit
get_qps = 10000  # GET requests per second limit
delete_qps = 5000

[blob_storage.s3_hybrid_single_az.retry_config]
max_retries = 3
base_delay_ms = 100
max_delay_ms = 5000

# Load configuration
# export FRACTALBITS_API_SERVER_CONFIG=/path/to/api_server.toml
# /opt/fractalbits/bin/api_server
```

--------------------------------

### Get Object Metadata using S3 Client

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Retrieves metadata for a specific object in an S3 bucket without downloading the object's content. Useful for checking content type, size, and ETag. Requires bucket name and object key.

```python
head_response = s3_client.head_object(Bucket='my-bucket', Key='data.txt')
print(f"Content-Type: {head_response['ContentType']}")
print(f"Content-Length: {head_response['ContentLength']}")
print(f"ETag: {head_response['ETag']}")
```

--------------------------------

### Docker Deployment for FractalBits

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Explains how to deploy FractalBits services using Docker for testing and development. Includes commands for building debug and release Docker images, running containers in the foreground or background with port customization, viewing logs, stopping containers, and running Docker directly with privileged access for `io_uring`.

```bash
# Build Docker image (debug build)
just docker build

# Build release Docker image for production
just docker build --release

# Run container in foreground
just docker run

# Run container with custom port
just docker run --port 9080

# Run container in background
just docker run --detach --name fractalbits-dev

# View container logs
just docker logs --name fractalbits-dev --follow

# Stop container
just docker stop --name fractalbits-dev

# Using Docker directly (requires --privileged for io_uring)
docker run --rm --privileged -p 8080:8080 \
    ghcr.io/fractalbits-labs/fractalbits-main:latest
```

--------------------------------

### Build FractalBits Components with 'just'

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

This code snippet demonstrates how to clone the FractalBits repository, initialize the repository, and build all its components using the 'just' command runner. This is a common first step for local development.

```bash
git clone https://github.com/fractalbits-labs/fractalbits-main.git
cd fractalbits-main

# Initialize repo
just repo init

# Build all components
just build
```

--------------------------------

### Log into AWS EC2 Instances and Run Benchmarks

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Shows how to log into EC2 instances within the deployed AWS infrastructure using AWS Systems Manager (SSM) and how to run pre-defined benchmark workloads on bench client nodes if the VPC was created with the `--with-bench` option.

```bash
# Log into ec2 instance nodes
aws ssm start-session --target <ec2-instance-id>

# If the VPC is created with `--with-bench`, you can log into bench_server to run
# pre-defined benchmark workloads (get_4k, put_4k, mixed_4k, get_64k, put_64k, mixed_64k)
WORKLOAD=get_4k /opt/fractalbits/bin/bench_start.sh
```

--------------------------------

### Build FractalBits Binaries for Deployment

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Instructions for building FractalBits binaries from source for deployment. This optional step requires `cargo-zigbuild` for cross-compilation and uses the `just deploy build` command.

```bash
# Make sure cargo-zigbuild is installed for cross-compilation
cargo install --locked cargo-zigbuild

# Build binaries for deployment
just deploy build
```

--------------------------------

### Run FractalBits Docker Container

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Instructions for running the FractalBits Docker container. Covers foreground execution, running with a custom port, detaching the container, and viewing logs. Requires `just` command-line tool.

```bash
# Run container (foreground)
just docker run

# Run container with custom port
just docker run --port 9080

# Run container in background
just docker run --detach --name fractalbits-dev

# View logs
just docker logs --name fractalbits-dev --follow

# Stop container
just docker stop --name fractalbits-dev
```

--------------------------------

### Basic S3 Operations using AWS CLI

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Demonstrates fundamental S3 operations such as creating a bucket, uploading an object, downloading an object, and listing objects within a bucket. These commands are executed using the AWS CLI after configuring the environment variables for a local S3 endpoint.

```bash
# Create a bucket
aws s3 mb s3://my-bucket

# Upload an object
echo 'Hello FractalBits!' > test.txt
aws s3 cp test.txt s3://my-bucket/

# Download an object
aws s3 cp s3://my-bucket/test.txt downloaded.txt

# List objects
aws s3 ls s3://my-bucket
```

--------------------------------

### Manage FractalBits API Keys with rss_admin

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Details the process of managing API keys for the FractalBits RSS service using the `rss_admin` command-line tool. Includes steps for connecting to the RSS instance via AWS SSM, creating new keys, listing existing keys, deleting keys, and viewing help information for API key commands.

```bash
# Connect to RSS instance via AWS SSM
ec2=i-0b97a853c3e223dc0  # RSS instance ID from 'just describe-stack'
aws ssm start-session --target=$ec2

# Create new API key
/opt/fractalbits/bin/rss_admin \
    --rss-addr=localhost:8088 \
    api-key create \
    --name my_application_key

# List existing API keys
/opt/fractalbits/bin/rss_admin \
    --rss-addr=localhost:8088 \
    api-key list

# Delete an API key
/opt/fractalbits/bin/rss_admin \
    --rss-addr=localhost:8088 \
    api-key delete \
    --name my_application_key

# Show all rss_admin API key commands
/opt/fractalbits/bin/rss_admin \
    --rss-addr=localhost:8088 \
    api-key --help
```

--------------------------------

### API Key Management

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Manages API access credentials using the `rss_admin` command-line tool.

```APIDOC
## API Key Management

### Description
This section details how to manage API keys for accessing FractalBits services using the `rss_admin` utility. It covers creating, listing, and deleting API keys.

### Method
CLI Command (`rss_admin`)

### Endpoint
N/A (CLI commands)

### Parameters
#### Command Line Arguments
- `--rss-addr` (string) - Required - The address and port of the RSS service (e.g., `localhost:8088`).
- `api-key` - Subcommand for API key operations.
  - `create` - Creates a new API key.
    - `--name` (string) - Required - The name for the new API key.
  - `list` - Lists all existing API keys.
  - `delete` - Deletes an API key.
    - `--name` (string) - Required - The name of the API key to delete.
  - `--help` - Displays help information for API key commands.

### Request Example
```bash
# Connect to RSS instance via AWS SSM (example step before using rss_admin)
ec2=i-0b97a853c3e223dc0  # RSS instance ID from 'just describe-stack'
aws ssm start-session --target=$ec2

# Create new API key
/opt/fractalbits/bin/rss_admin \
    --rss-addr=localhost:8088 \
    api-key create \
    --name my_application_key

# List existing API keys
/opt/fractalbits/bin/rss_admin \
    --rss-addr=localhost:8088 \
    api-key list

# Delete an API key
/opt/fractalbits/bin/rss_admin \
    --rss-addr=localhost:8088 \
    api-key delete \
    --name my_application_key

# Show all rss_admin API key commands
/opt/fractalbits/bin/rss_admin \
    --rss-addr=localhost:8088 \
    api-key --help
```

### Response
#### Success Response (CLI Output)
- `create`: Displays the generated Access Key ID and Secret Access Key.
- `list`: Lists the names and IDs of existing API keys.
- `delete`: Confirmation message upon successful deletion.

#### Response Example
```
# Output for 'create':
Access Key name: my_application_key
Access Key ID: 52ff329f0b4c97dc8726f7cf
Secret Access Key: 994e92eb3a020bce69ecc05243b627707f0fc40e2bb2be6732c092e2cf51a4ea

# Output for 'list':
API Keys:
=========
- my_application_key (52ff329f0b4c97dc8726f7cf)
- production_key (a3bc45de67fg89hi01jk23lm)

# Output for 'delete':
API key 'my_application_key' deleted successfully.
```
```

--------------------------------

### List Existing API Keys using rss_admin (Bash)

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/docs/API_KEY_MANAGEMENT.md

Lists all existing API keys managed by the RSS instance. This command displays the Access Key ID and the name of each key, but not the Secret Access Key.

```bash
/opt/fractalbits/bin/rss_admin --rss-addr=localhost:8088 api-key list
```

--------------------------------

### Describe VPC Stack Information (Bash)

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/docs/API_KEY_MANAGEMENT.md

Retrieves information about all instances within the VPC stack, including instance IDs, states, types, and private IP addresses. This is crucial for identifying the correct RSS instance.

```bash
just describe-stack
```

--------------------------------

### Build FractalBits Docker Image

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Commands to build the Docker image for FractalBits. Supports building a debug version by default or a release version using the `--release` flag. Requires `just` command-line tool.

```bash
# Build Docker image (uses debug build by default)
just docker build

# Build release Docker image
just docker build --release
```

--------------------------------

### S3 API Multipart Upload Operations with AWS CLI

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Illustrates the process of uploading large files using S3's multipart upload functionality via the AWS CLI. This includes initiating the upload, uploading individual parts, listing parts, completing the upload, aborting an upload, and listing in-progress multipart uploads. This is crucial for efficient handling of large objects.

```bash
# CreateMultipartUpload - Initiate multipart upload
UPLOAD_ID=$(aws s3api create-multipart-upload \
    --bucket my-bucket \
    --key large-file.bin \
    --query 'UploadId' \
    --output text)

# UploadPart - Upload individual parts (minimum 5MB except last part)
ETAG1=$(aws s3api upload-part \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID \
    --part-number 1 \
    --body part1.bin \
    --query 'ETag' \
    --output text)

ETAG2=$(aws s3api upload-part \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID \
    --part-number 2 \
    --body part2.bin \
    --query 'ETag' \
    --output text)

# ListParts - List uploaded parts
aws s3api list-parts \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID

# CompleteMultipartUpload - Finalize the upload
aws s3api complete-multipart-upload \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID \
    --multipart-upload "{\"Parts\": [{\"ETag\": $ETAG1, \"PartNumber\": 1}, {\"ETag\": $ETAG2, \"PartNumber\": 2}]}"

# AbortMultipartUpload - Cancel an in-progress upload
aws s3api abort-multipart-upload \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID

# ListMultipartUploads - List all in-progress multipart uploads
aws s3api list-multipart-uploads --bucket my-bucket
```

--------------------------------

### Run FractalBits with Docker

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

This snippet shows how to run the FractalBits main project as a Docker container with a persistent data volume. It maps port 8080 and mounts a named volume '/data' for data persistence. It also includes a command to execute bash inside the running container.

```shell
docker run -d --privileged --name fractalbits \
    -p 8080:8080 \
    -v fractalbits-data:/data \
    ghcr.io/fractalbits-labs/fractalbits-main:latest

docker exec -it fractalbits /bin/bash
```

--------------------------------

### Run FractalBits Docker Container Directly

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Provides direct `docker run` commands to launch the FractalBits container. Emphasizes the need for `--privileged` mode due to the storage engine's use of io_uring. Supports running the latest image, a specific version by commit SHA, or a custom-built image.

```bash
# Run the latest image
docker run --rm --privileged -p 8080:8080 ghcr.io/fractalbits-labs/fractalbits-main:latest

# Run a specific version
docker run --rm --privileged -p 8080:8080 ghcr.io/fractalbits-labs/fractalbits-main:<commit-sha>

# Run your custom-built image (after `cargo xtask docker build`)
docker run --rm --privileged -p 8080:8080 fractalbits:latest

# Run in background with persistent data
docker run -d --privileged --name fractalbits \
    -p 8080:8080 \
    -v fractalbits-data:/data \
    ghcr.io/fractalbits-labs/fractalbits-main:latest
```

--------------------------------

### AWS SDK Integration with FractalBits (Rust)

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

This Rust code snippet demonstrates how to use the AWS SDK for Rust to interact with FractalBits. It covers creating buckets, uploading, downloading, and deleting objects, including multipart uploads for large files. Ensure the 'aws-sdk-s3' and 'tokio' crates are added as dependencies.

```rust
use aws_sdk_s3::{Client, Config, Credentials, Region};
use aws_sdk_s3::primitives::ByteStream;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure S3 client for FractalBits
    let config = Config::builder()
        .region(Region::new("localdev"))
        .endpoint_url("http://localhost:8080")
        .credentials_provider(Credentials::new(
            "test_api_key",
            "test_api_secret",
            None,
            None,
            "fractalbits"
        ))
        .build();

    let client = Client::from_conf(config);

    // Create bucket
    client.create_bucket()
        .bucket("my-bucket")
        .send()
        .await?;

    // Upload object
    let data = ByteStream::from_static(b"Hello FractalBits!");
    client.put_object()
        .bucket("my-bucket")
        .key("test.txt")
        .body(data)
        .send()
        .await?;

    // Download object
    let result = client.get_object()
        .bucket("my-bucket")
        .key("test.txt")
        .send()
        .await?;

    let body = result.body.collect().await?;
    println!("Downloaded: {}", String::from_utf8_lossy(body.as_ref()));

    // Multipart upload for large files
    let upload = client.create_multipart_upload()
        .bucket("my-bucket")
        .key("large-file.bin")
        .send()
        .await?;

    let upload_id = upload.upload_id().unwrap();

    let part1_data = ByteStream::from(vec![0x42; 5 * 1024 * 1024]);
    let part1 = client.upload_part()
        .bucket("my-bucket")
        .key("large-file.bin")
        .upload_id(upload_id)
        .part_number(1)
        .body(part1_data)
        .send()
        .await?;

    // Complete multipart upload
    use aws_sdk_s3::types::{CompletedMultipartUpload, CompletedPart};

    let completed_parts = CompletedPart::builder()
        .part_number(1)
        .e_tag(part1.e_tag().unwrap())
        .build();

    let completed_upload = CompletedMultipartUpload::builder()
        .parts(completed_parts)
        .build();

    client.complete_multipart_upload()
        .bucket("my-bucket")
        .key("large-file.bin")
        .upload_id(upload_id)
        .multipart_upload(completed_upload)
        .send()
        .await?;

    // List objects
    let objects = client.list_objects_v2()
        .bucket("my-bucket")
        .prefix("test")
        .send()
        .await?;

    for obj in objects.contents() {
        println!("Object: {} ({}B)", obj.key().unwrap(), obj.size().unwrap());
    }

    // Delete object
    client.delete_object()
        .bucket("my-bucket")
        .key("test.txt")
        .send()
        .await?;

    // Delete bucket
    client.delete_bucket()
        .bucket("my-bucket")
        .send()
        .await?;

    Ok(())
}

```

--------------------------------

### Create New API Key using rss_admin (Bash)

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/docs/API_KEY_MANAGEMENT.md

Creates a new API key for the RSS instance using the `rss_admin` tool. This command requires the name for the new key and outputs the Access Key ID and Secret Access Key. The Secret Access Key must be saved immediately.

```bash
/opt/fractalbits/bin/rss_admin --rss-addr=localhost:8088 api-key create --name <KEY_NAME>
```

```bash
/opt/fractalbits/bin/rss_admin --rss-addr=localhost:8088 api-key create --name my_cloud_api_key
```

--------------------------------

### S3 API Object Operations with AWS CLI

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Demonstrates common S3 object operations using the AWS CLI, including uploading, downloading, retrieving metadata, copying, and deleting objects. These commands are essential for managing data within FractalBits buckets and require the AWS CLI to be configured for the FractalBits endpoint.

```bash
# PutObject - Upload an object
echo 'Hello FractalBits!' > test.txt
aws s3 cp test.txt s3://my-bucket/test.txt

# GetObject - Download an object
aws s3 cp s3://my-bucket/test.txt downloaded.txt

# HeadObject - Get object metadata
aws s3api head-object --bucket my-bucket --key test.txt

# CopyObject - Copy an object within bucket
aws s3 cp s3://my-bucket/test.txt s3://my-bucket/test-copy.txt

# DeleteObject - Remove an object
aws s3 rm s3://my-bucket/test.txt

# GetObjectAttributes - Get extended object attributes
aws s3api get-object-attributes --bucket my-bucket --key test.txt \
    --object-attributes ETag Checksum StorageClass ObjectSize
```

--------------------------------

### Atomic S3 Object and Folder Rename with Boto3

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Showcases FractalBits' custom extension for atomic rename operations using the Python SDK (boto3). It demonstrates renaming individual objects and entire folders by utilizing the `x-amz-rename-source` custom header. Includes basic error handling for these operations.

```python
import boto3

# Configure boto3 client
s3_client = boto3.client(
    's3',
    endpoint_url='http://localhost:8080',
    aws_access_key_id='test_api_key',
    aws_secret_access_key='test_api_secret',
    region_name='localdev'
)

# RenameObject - Atomically rename an object within bucket
# Uses custom x-amz-rename-source header
response = s3_client.put_object(
    Bucket='my-bucket',
    Key='new-name.txt',
    Metadata={
        'x-amz-rename-source': '/my-bucket/old-name.txt'
    }
)
print(f"Object renamed: {response['ResponseMetadata']['HTTPStatusCode']}")

# RenameFolder - Atomically rename entire directory prefix
# All objects with the old prefix are moved to new prefix
response = s3_client.put_object(
    Bucket='my-bucket',
    Key='new-folder/',
    Metadata={
        'x-amz-rename-source': '/my-bucket/old-folder/'
    }
)
print(f"Folder renamed: {response['ResponseMetadata']['HTTPStatusCode']}")

# Error handling for rename operations
try:
    s3_client.put_object(
        Bucket='my-bucket',
        Key='destination/',
        Metadata={'x-amz-rename-source': '/my-bucket/source/'}
    )
except s3_client.exceptions.NoSuchKey:
    print("Source object or folder does not exist")
except Exception as e:
    print(f"Rename failed: {e}")
```

--------------------------------

### List Operations

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/docs/S3_API_COMPATIBILITY.md

APIs for listing objects within a bucket, supporting both v1 and v2.

```APIDOC
## List Operations

### Description
APIs for retrieving lists of objects within a bucket.

### Supported Operations
- **ListObjects (v1)**: Lists objects in a bucket using the v1 API.
- **ListObjectsV2**: Lists objects in a bucket using the v2 API.

*Note: Objects are returned in lexicographical order, which may differ from S3 Express One Zone behavior.*
```

--------------------------------

### Bucket Operations

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/docs/S3_API_COMPATIBILITY.md

Operations for managing buckets, including creation, deletion, and listing.

```APIDOC
## Bucket Operations

### Description
Operations for managing buckets, such as creating, deleting, and listing them.

### Supported Operations
- **CreateBucket**: Creates a new bucket.
- **DeleteBucket**: Deletes an existing bucket.
- **HeadBucket**: Retrieves metadata about a bucket.
- **ListBuckets**: Lists all buckets owned by the authenticated sender.
```

--------------------------------

### Run S3 API Compatibility Tests

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Executes the S3 API compatibility test suite for FractalBits. The `just precheckin --s3-api-only` command runs only the S3 API tests, while `just precheckin` includes all unit tests.

```bash
# Run S3 API regression tests
just precheckin --s3-api-only

# Run with all unit tests also
just precheckin
```

--------------------------------

### S3 API - List Objects

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Lists objects within an S3 bucket, with options for directory-like structures and recursive listing.

```APIDOC
## AWS S3 API - List Objects

### Description
Provides commands to list objects in an S3 bucket. Supports filtering by prefix and delimiter for directory-like structures, as well as recursive listing.

### Method
CLI Command

### Endpoint
N/A (CLI commands)

### Parameters
#### Command Line Arguments
- `--bucket` (string) - Required - The name of the S3 bucket.
- `--prefix` (string) - Optional - Filters objects starting with this prefix.
- `--delimiter` (string) - Optional - Used with `--prefix` to simulate directory structures.
- `--recursive` - Optional flag for recursive listing.

### Request Example
```bash
# List with delimiter for directory-like structure
aws s3api list-objects-v2 \
    --bucket my-bucket \
    --prefix "images/" \
    --delimiter "/"

# List all objects recursively
aws s3 ls s3://my-bucket --recursive
```

### Response
#### Success Response (CLI Output)
- `CommonPrefixes[]` - For directory-like listing.
- Object list - For recursive listing.

#### Response Example
```
# CommonPrefixes for directory-like listing:
CommonPrefixes: [
    {
        "Prefix": "images/avatars/"
    },
    {
        "Prefix": "images/thumbnails/"
    }
]

# Object list for recursive listing:
2023-10-27 10:00:00       1024 file1.txt
2023-10-27 10:05:00       2048 images/photo.jpg
```
```

--------------------------------

### Export AWS Environment Variables for Local Development

Source: https://github.com/fractalbits-labs/fractalbits-main/blob/main/README.md

Sets up essential AWS environment variables to configure the AWS CLI to interact with a local S3 endpoint. This is crucial for local development and testing against a local instance of FractalBits.

```bash
export AWS_DEFAULT_REGION=localdev
export AWS_ENDPOINT_URL_S3=http://localhost:8080
export AWS_ACCESS_KEY_ID=test_api_key
export AWS_SECRET_ACCESS_KEY=test_api_secret
```

--------------------------------

### Extension API - Atomic Rename Operations

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

Provides custom API extensions for atomic rename operations on objects and folders, which are not standard S3 features.

```APIDOC
## Extension API - Atomic Rename Operations

### Description
FractalBits offers unique extension API capabilities for performing atomic rename operations on objects and entire directories (prefixes) within an S3 bucket. These operations ensure atomicity, which is not natively supported by standard S3 operations.

### Method
`PUT` (using custom headers for rename)

### Endpoint
`/` (Object or Folder Key)

### Parameters
#### Headers
- `x-amz-rename-source` (string) - Required - Specifies the source path for the rename operation. Format: `/bucket-name/old-key` or `/bucket-name/old-prefix/`.

#### Request Body
Not applicable for rename operations; the operation is defined by the `x-amz-rename-source` header.

### Request Example (Python SDK with boto3)
```python
import boto3

# Configure boto3 client for FractalBits endpoint
s3_client = boto3.client(
    's3',
    endpoint_url='http://localhost:8080', # Or your FractalBits endpoint
    aws_access_key_id='test_api_key',
    aws_secret_access_key='test_api_secret',
    region_name='localdev'
)

# RenameObject - Atomically rename an object
try:
    response = s3_client.put_object(
        Bucket='my-bucket',
        Key='new-name.txt',
        Metadata={'x-amz-rename-source': '/my-bucket/old-name.txt'}
    )
    print(f"Object renamed successfully. Status code: {response['ResponseMetadata']['HTTPStatusCode']}")
except Exception as e:
    print(f"Object rename failed: {e}")

# RenameFolder - Atomically rename an entire directory prefix
try:
    response = s3_client.put_object(
        Bucket='my-bucket',
        Key='new-folder/', # The new prefix for the folder
        Metadata={'x-amz-rename-source': '/my-bucket/old-folder/'} # The old prefix
    )
    print(f"Folder renamed successfully. Status code: {response['ResponseMetadata']['HTTPStatusCode']}")
except Exception as e:
    print(f"Folder rename failed: {e}")
```

### Response
#### Success Response (200 OK)
- Typically returns standard S3 `put_object` response metadata upon success.

#### Response Example
```json
{
    "ResponseMetadata": {
        "RequestId": "some-request-id",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "content-length": "0",
            "date": "Fri, 27 Oct 2023 10:30:00 GMT",
            "server": "fractalbits"
        },
        "RetryAttempts": 0
    }
}
```

### Error Handling
#### Common Errors
- `NoSuchKey`: The source object or folder specified in `x-amz-rename-source` does not exist.
- `Exception`: Catches general exceptions during the rename process.

#### Error Example (Python SDK)
```python
try:
    # ... (rename operation code) ...
except s3_client.exceptions.NoSuchKey:
    print("Error: Source object or folder does not exist.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```
```

--------------------------------

### S3 Multipart Upload

Source: https://context7.com/fractalbits-labs/fractalbits-main/llms.txt

APIs for efficiently handling large objects through multipart upload, including initiation, part uploading, listing, completion, and abortion.

```APIDOC
## S3 Multipart Upload

### Description
Efficient handling of large objects through multipart upload operations.

### Methods and Endpoints
This section covers operations like CreateMultipartUpload, UploadPart, ListParts, CompleteMultipartUpload, AbortMultipartUpload, and ListMultipartUploads.

### Request Example (CreateMultipartUpload)
```bash
# Initiate multipart upload
UPLOAD_ID=$(aws s3api create-multipart-upload \
    --bucket my-bucket \
    --key large-file.bin \
    --query 'UploadId' \
    --output text)
```

### Request Example (UploadPart)
```bash
# Upload individual parts (minimum 5MB except last part)
ETAG1=$(aws s3api upload-part \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID \
    --part-number 1 \
    --body part1.bin \
    --query 'ETag' \
    --output text)

ETAG2=$(aws s3api upload-part \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID \
    --part-number 2 \
    --body part2.bin \
    --query 'ETag' \
    --output text)
```

### Request Example (ListParts)
```bash
# List uploaded parts
aws s3api list-parts \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID
```

### Request Example (CompleteMultipartUpload)
```bash
# Finalize the upload
aws s3api complete-multipart-upload \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID \
    --multipart-upload "{\"Parts\": [{\"ETag\": $ETAG1, \"PartNumber\": 1}, {\"ETag\": $ETAG2, \"PartNumber\": 2}]}"
```

### Request Example (AbortMultipartUpload)
```bash
# Cancel an in-progress upload
aws s3api abort-multipart-upload \
    --bucket my-bucket \
    --key large-file.bin \
    --upload-id $UPLOAD_ID
```

### Request Example (ListMultipartUploads)
```bash
# List all in-progress multipart uploads
aws s3api list-multipart-uploads --bucket my-bucket
```
```