performance

Performance Benchmark Example

This example demonstrates performance testing of the Mach storage system with various workloads.

Features

• Sequential and concurrent read/write benchmarks
• Small, medium, and large object testing
• Mixed workload simulation
• Multipart upload performance testing
• Detailed metrics and statistics

Running the benchmark

cd examples/performance
go run main.go [storage-path]

Default storage path: ./performance-data

Benchmark Types

1. Sequential Operations

• Sequential writes and reads
• Measures single-threaded performance
• Tests different object sizes (1KB, 1MB, 10MB)

2. Concurrent Operations

• Multi-threaded reads and writes
• Scales with CPU cores
• Tests system under concurrent load

3. Mixed Workload

• Simulates real-world usage patterns
• Configurable read/write ratio
• Runs for specified duration

4. Multipart Upload

• Tests large file upload performance
• Configurable file and part sizes
• Measures end-to-end upload time

Sample Output

Starting performance benchmarks...
Storage path: ./performance-data
CPU cores: 8
GOMAXPROCS: 8

--- Small Objects (1KB) ---
=== Sequential Write ===
Duration:        2.5s
Operations:      1000
Ops/sec:         400.00
Throughput:      0.39 MB/s
Avg Latency:     2.5ms

=== Sequential Read ===
Duration:        1.2s
Operations:      1000
Ops/sec:         833.33
Throughput:      0.81 MB/s
Avg Latency:     1.2ms

--- Medium Objects (1MB) ---
=== Concurrent Write (8 workers) ===
Duration:        5.2s
Operations:      100
Ops/sec:         19.23
Throughput:      19.23 MB/s
Avg Latency:     52ms

BENCHMARK RESULTS SUMMARY
================================================================================
Final metrics:
  Read Ops:       2110
  Write Ops:      1210
  Write Bytes:    125829120 (120.00 MB)
  Error Count:    0

Configuration

The benchmark automatically configures the storage for optimal performance:

• Increased concurrent upload/download limits
• Larger buffer sizes (1MB)
• Memory mapping enabled
• Checksum verification disabled for speed

Interpreting Results

• Ops/sec: Operations per second
• Throughput: Data transfer rate in MB/s
• Latency: Time per operation
• Error Count: Failed operations

Use these metrics to:

• Compare different configurations
• Identify performance bottlenecks
• Validate system capacity
• Plan for production workloads

### examples/webserver/README.md
```markdown
# Web Server Example

This example demonstrates how to build a REST API server using the Mach storage system.

## Features

- RESTful API for bucket and object operations
- Health check endpoint
- Storage statistics
- Request logging
- Metadata support via HTTP headers

## Running the server

```bash
cd examples/webserver
go run main.go [storage-path] [port]

Default values:

• storage-path: ./webserver-data
• port: 8080

API Endpoints

Health Check

GET /health

Storage Statistics

GET /stats

Bucket Operations

# List buckets
GET /buckets

# Create bucket
POST /buckets/{bucket-name}

# Delete bucket
DELETE /buckets/{bucket-name}

Object Operations

# List objects in bucket
GET /objects/{bucket-name}?prefix=&marker=&delimiter=&max-keys=

# Get object
GET /objects/{bucket-name}/{object-key}

# Put object (with metadata)
PUT /objects/{bucket-name}/{object-key}
Content-Type: text/plain
X-Meta-Author: john
X-Meta-Version: 1.0

# Delete object
DELETE /objects/{bucket-name}/{object-key}

Example Usage

# Start the server
go run main.go

# Create a bucket
curl -X POST http://localhost:8080/buckets/my-bucket

# Upload a file with metadata
curl -X PUT http://localhost:8080/objects/my-bucket/hello.txt \
  -H "Content-Type: text/plain" \
  -H "X-Meta-Author: john" \
  -H "X-Meta-Version: 1.0" \
  -d "Hello, World!"

# Download the file
curl http://localhost:8080/objects/my-bucket/hello.txt

# List objects
curl http://localhost:8080/objects/my-bucket

# Get statistics
curl http://localhost:8080/stats

# Health check
curl http://localhost:8080/health

Response Examples

Health Check Response

{
  "status": "healthy",
  "metrics": {
    "readOps": 150,
    "writeOps": 75,
    "errorCount": 0
  }
}

List Buckets Response

[
  {
    "name": "my-bucket",
    "creationDate": "2024-01-01T12:00:00Z"
  }
]

List Objects Response

{
  "objects": [
    {
      "key": "hello.txt",
      "size": 13,
      "lastModified": "2024-01-01T12:00:00Z",
      "etag": "65a8e27d8879283831b664bd8b7f0ad4"
    }
  ],
  "commonPrefixes": []
}

Statistics Response

{
  "storage": {
    "bucketCount": 1,
    "objectCount": 5,
    "totalSize": 1024
  },
  "metrics": {
    "readOps": 150,
    "writeOps": 75,
    "deleteOps": 10,
    "listOps": 25,
    "readBytes": 51200,
    "writeBytes": 25600,
    "errorCount": 0
  },
  "disk": {
    "total": 1000000000,
    "free": 800000000,
    "used": 200000000
  }
}

Error Responses

The server returns appropriate HTTP status codes:

• 200 OK - Success
• 201 Created - Resource created
• 400 Bad Request - Invalid request
• 404 Not Found - Resource not found
• 409 Conflict - Resource already exists or bucket not empty
• 500 Internal Server Error - Server error
• 503 Service Unavailable - Health check failed

Metadata Headers

Custom metadata can be set using X-Meta- headers:

curl -X PUT http://localhost:8080/objects/my-bucket/document.pdf \
  -H "Content-Type: application/pdf" \
  -H "X-Meta-Author: john.doe" \
  -H "X-Meta-Department: engineering" \
  -H "X-Meta-Version: 1.2" \
  --data-binary @document.pdf

The metadata will be returned in response headers when retrieving the object.

Query Parameters

List Objects Parameters

• prefix - Only return objects whose keys begin with this prefix
• marker - Start listing after this key
• delimiter - Character used to group keys
• max-keys - Maximum number of keys to return (default: 1000)

Example:

curl "http://localhost:8080/objects/my-bucket?prefix=docs/&max-keys=50"