Storage API

The Storage API provides file storage operations using Cloudflare R2.

Overview

Procedure	Type	Auth	Description
storage.getStats	Query	No	Get storage statistics

Procedures

storage.getStats

Get storage usage statistics and bucket information.

Type: Query Auth Required: No

Response

{
  totalStorage: number;      // Total storage capacity (bytes)
  usedStorage: number;       // Used storage (bytes)
  availableStorage: number;  // Available storage (bytes)
  buckets: Array<{
    name: string;            // Bucket name
    size: number;            // Used size (bytes)
    fileCount: number;       // Number of files
    lastModified: string;    // Last modification date
  }>;
}

Example

curl -X GET "https://api.itms.solutions/trpc/storage.getStats"

Response Example

{
  "result": {
    "data": {
      "json": {
        "totalStorage": 10737418240,
        "usedStorage": 1073741824,
        "availableStorage": 9663676416,
        "buckets": [
          {
            "name": "smart-city-storage",
            "size": 1073741824,
            "fileCount": 1250,
            "lastModified": "2024-11-15T12:00:00.000Z"
          }
        ]
      }
    }
  }
}

Storage Architecture

Cloudflare R2

The storage system uses Cloudflare R2, an S3-compatible object storage service:

• Global Distribution - Files are replicated across Cloudflare's edge network
• Zero Egress Fees - No charges for data transfer out
• S3 Compatible - Works with existing S3 tools and SDKs

File Organization

smart-city-storage/
├── events/              # Traffic event images
│   ├── 2024/
│   │   ├── 11/
│   │   │   └── {event-id}.jpg
├── violations/          # Violation evidence
│   └── {violation-id}/
│       ├── image.jpg
│       └── metadata.json
├── reports/            # Generated reports
│   └── {report-id}.pdf
└── sensors/            # Sensor media
    └── {sensor-id}/
        └── snapshot.jpg

Storage Limits

Limit	Value
Default Quota	10 GB
Max File Size	100 MB
Max Files per Request	1

File Types

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)
• GIF (.gif)

Supported Document Formats

• PDF (.pdf)
• CSV (.csv)
• JSON (.json)

Planned Features

The following storage features are planned for future releases:

storage.getUploadUrl

Generate a pre-signed URL for direct upload to R2.

// Input
{
  filename: string;
  contentType: string;
  folder?: string;
}

// Response
{
  uploadUrl: string;    // Pre-signed upload URL
  fileKey: string;      // Storage key
  expiresAt: string;    // URL expiration
}

storage.confirmUpload

Confirm a file upload and update metadata.

// Input
{
  fileKey: string;
  metadata?: Record<string, string>;
}

// Response
{
  success: boolean;
  file: {
    key: string;
    url: string;
    size: number;
    contentType: string;
  };
}

storage.deleteFile

Delete a file from storage.

// Input
{
  fileKey: string;
}

// Response
{
  success: boolean;
}

storage.listFiles

List files in a folder.

// Input
{
  folder?: string;
  limit?: number;
  cursor?: string;
}

// Response
{
  files: Array<{
    key: string;
    size: number;
    lastModified: string;
    contentType: string;
  }>;
  nextCursor?: string;
}

R2 Configuration

The storage is configured via wrangler.toml:

[[r2_buckets]]
binding = "R2"
bucket_name = "smart-city-storage"

Public Access

Files can be served through Cloudflare's public access:

https://storage.itms.solutions/{file-key}

Or through the worker:

https://api.itms.solutions/storage/{file-key}