Collection Creation Worker

This Cloudflare Worker handles the creation, retrieval, updating, and deletion of collections on the Ramus Network.

Features

• Create public or private collections
• Retrieve collection details
• Update collection metadata
• Delete collections
• List user's collections
• List public collections
• JWT-based authentication
• D1 for relational persistence
• KV for metadata caching

API Endpoints

Create Collection

• URL: /collections
• Method: POST
• Auth Required: Yes (Bearer Token)
• Request Body:

  {
    "name": "Collection Name",
    "description": "Collection Description",
    "isPublic": true
  }

• Success Response:

  {
    "success": true,
    "message": "Collection created successfully",
    "collection": {
      "id": "uuid",
      "name": "Collection Name",
      "description": "Collection Description",
      "ownerId": 123,
      "isPublic": true,
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  }

Get Collection

• URL: /collections/:id
• Method: GET
• Auth Required: Yes (for private collections)
• Success Response:

  {
    "success": true,
    "collection": {
      "id": "uuid",
      "name": "Collection Name",
      "description": "Collection Description",
      "ownerId": 123,
      "isPublic": true,
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  }

Update Collection

• URL: /collections/:id
• Method: PUT
• Auth Required: Yes (Bearer Token)
• Request Body:

  {
    "name": "New Name",
    "description": "New Description",
    "isPublic": false
  }

• Success Response:

  {
    "success": true,
    "message": "Collection updated successfully",
    "collection": {
      "id": "uuid",
      "name": "New Name",
      "description": "New Description",
      "ownerId": 123,
      "isPublic": false,
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  }

Delete Collection

• URL: /collections/:id
• Method: DELETE
• Auth Required: Yes (Bearer Token)
• Success Response:

  {
    "success": true,
    "message": "Collection deleted successfully"
  }

List User's Collections

• URL: /collections
• Method: GET
• Auth Required: Yes (Bearer Token)
• Success Response:

  {
    "success": true,
    "collections": [
      {
        "id": "uuid",
        "name": "Collection Name",
        "description": "Collection Description",
        "ownerId": 123,
        "isPublic": true,
        "createdAt": "2023-01-01T00:00:00.000Z",
        "updatedAt": "2023-01-01T00:00:00.000Z"
      }
    ]
  }

List Public Collections

• URL: /public-collections
• Method: GET
• Auth Required: No
• Success Response:

  {
    "success": true,
    "collections": [
      {
        "id": "uuid",
        "name": "Collection Name",
        "description": "Collection Description",
        "ownerId": 123,
        "isPublic": true,
        "createdAt": "2023-01-01T00:00:00.000Z",
        "updatedAt": "2023-01-01T00:00:00.000Z"
      }
    ]
  }

Authentication

This worker uses the same authentication system as the login worker. It verifies JWT tokens by checking the session in the KV store.

To authenticate requests, include a Bearer token in the Authorization header:

Authorization: Bearer <session-token>

Setup

1. Update the wrangler.jsonc file with your D1 database ID and KV namespace IDs.
2. Deploy the worker using Wrangler:

cd create_collection
npm install
npx wrangler deploy

Database Schema

The collections table schema is defined in database/schema.sql:

CREATE TABLE collections (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT,
    owner_id INTEGER NOT NULL,
    is_public BOOLEAN NOT NULL DEFAULT 0,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
    FOREIGN KEY (owner_id) REFERENCES users(id)
);

Data Storage Schema

D1 Database

The collections service stores data in a D1 database with the following schema:

Collections Table

Column	Type	Description
id	TEXT	Primary key, UUID for the collection
name	TEXT	Collection name
description	TEXT	Collection description (optional)
owner_id	INTEGER	Foreign key to the users table
is_public	BOOLEAN	Whether the collection is publicly accessible
created_at	TEXT	Collection creation timestamp
updated_at	TEXT	Collection last updated timestamp

This table relates to the users table in the authentication service using the owner_id foreign key.

KV Storage

Collection metadata is cached in KV for faster retrieval:

Collections KV Namespace

Key Format	Value Format (JSON)	Description
collection_${collectionId}	{ "id": string, "name": string, "isPublic": boolean, "ownerId": number }	Collection metadata cache
user_collections_${userId}	string[] (array of collection IDs)	List of user's collection IDs
public_collections	string[] (array of collection IDs)	List of public collection IDs

The KV caching strategy improves read performance by:

1. Storing lightweight collection metadata to reduce D1 queries
2. Maintaining lists of collections by user and public status
3. Automatically invalidating cache entries when collections are updated or deleted

KV Caching

Basic collection metadata (name, isPublic, ownerId) is cached in KV for faster retrieval. The KV is updated whenever the collection metadata changes in D1.

The caching system follows these principles:

• Write-through caching: When collections are created or updated in D1, the KV cache is updated simultaneously
• Cache invalidation: When collections are deleted, the corresponding KV entries are removed
• TTL: Cache entries have time-to-live settings to prevent stale data
• Lazy loading: Some collection lists are only cached when first requested

Cache Update Patterns

Operation	D1 Action	KV Cache Actions
Create Collection	Insert row	Add to collection_${id}, update user and public lists
Update Collection	Update row	Update collection_${id}, potentially update public list
Delete Collection	Delete row	Remove from all related KV entries
List Collections	Query by filters	Read/write to appropriate list caches