@resourcexjs/server

ResourceX Registry Server - HTTP API server for hosting and serving ResourceX resources.

Installation

bun add @resourcexjs/server @resourcexjs/node-provider
# or
npm install @resourcexjs/server @resourcexjs/node-provider

Overview

This package provides three levels of abstraction for building a ResourceX registry server:

1. Hono Server - Ready-to-use server with all endpoints configured
2. Handlers - Framework-agnostic request handlers for custom integrations
3. Protocol - Type definitions and constants for building clients

Quick Start

import { createRegistryServer } from "@resourcexjs/server";
import { FileSystemRXAStore, FileSystemRXMStore } from "@resourcexjs/node-provider";

const server = createRegistryServer({
  rxaStore: new FileSystemRXAStore("./data/blobs"),
  rxmStore: new FileSystemRXMStore("./data/manifests"),
});

// Bun
Bun.serve({ fetch: server.fetch, port: 3000 });

// Node.js (with @hono/node-server)
import { serve } from "@hono/node-server";
serve({ fetch: server.fetch, port: 3000 });

API

createRegistryServer(config)

Creates a Hono app with all registry endpoints configured.

import { createRegistryServer } from "@resourcexjs/server";
import { FileSystemRXAStore, FileSystemRXMStore } from "@resourcexjs/node-provider";

const server = createRegistryServer({
  rxaStore: new FileSystemRXAStore("./data/blobs"),
  rxmStore: new FileSystemRXMStore("./data/manifests"),
  basePath: "", // Optional: API route prefix (default: "")
  cors: true, // Optional: Enable CORS (default: true)
});

Config Interface

interface RegistryServerConfig {
  rxaStore: RXAStore; // Content-addressable blob storage
  rxmStore: RXMStore; // Manifest storage
  basePath?: string; // API route prefix (default: "")
  cors?: boolean; // Enable CORS (default: true)
}

Handlers

Framework-agnostic handlers for custom server integrations (Next.js, Express, etc.).

import {
  handlePublish,
  handleGetResource,
  handleHeadResource,
  handleDeleteResource,
  handleGetContent,
  handleSearch,
  CASRegistry,
} from "@resourcexjs/server";
import { FileSystemRXAStore, FileSystemRXMStore } from "@resourcexjs/node-provider";

const registry = new CASRegistry(
  new FileSystemRXAStore("./data/blobs"),
  new FileSystemRXMStore("./data/manifests")
);

// Next.js Route Handler example
export async function POST(request: Request) {
  return handlePublish(request, registry);
}

Handler Functions

| Handler | Description | | ---------------------------------------------- | -------------------------------------- | | handlePublish(request, registry) | Process multipart form publish request | | handleGetResource(locator, registry) | Get resource manifest | | handleHeadResource(locator, registry) | Check resource existence | | handleDeleteResource(locator, registry) | Delete a resource | | handleGetContent(locator, registry) | Download resource archive | | handleSearch(query, limit, offset, registry) | Search resources |

API Endpoints

All endpoints are prefixed with /api/v1.

GET /api/v1/health

Health check endpoint.

Response:

{ "status": "ok" }

POST /api/v1/publish

Publish a resource to the registry.

Content-Type: multipart/form-data

Fields:

• locator (string) - Resource locator (e.g., hello:1.0.0)
• manifest (file) - JSON manifest file
• content (file) - Archive file (tar.gz)

Response (201):

{ "locator": "hello:1.0.0" }

GET /api/v1/resource/:locator

Get resource manifest.

Response (200):

{
  "name": "hello",
  "type": "text",
  "tag": "1.0.0",
  "path": "prompts"
}

HEAD /api/v1/resource/:locator

Check if resource exists.

Response: 200 if exists, 404 if not.

DELETE /api/v1/resource/:locator

Delete a resource.

Response: 204 on success.

GET /api/v1/content/:locator

Download resource archive.

Response: Binary application/gzip content.

GET /api/v1/search

Search for resources.

Query Parameters:

• q (string, optional) - Search query
• limit (number, default: 100) - Max results
• offset (number, default: 0) - Pagination offset

Response (200):

{
  "results": [
    {
      "locator": "hello:1.0.0",
      "name": "hello",
      "type": "text",
      "tag": "1.0.0"
    }
  ],
  "total": 1
}

Protocol

Type definitions and constants for building clients.

import {
  API_VERSION, // "v1"
  API_PREFIX, // "/api/v1"
  ENDPOINTS, // { publish, resource, content, search, health }
  CONTENT_TYPES, // { json, binary, formData }
  ERROR_CODES, // Error code constants
  buildResourceUrl, // Build resource URL
  buildContentUrl, // Build content URL
  buildPublishUrl, // Build publish URL
  buildSearchUrl, // Build search URL with params
} from "@resourcexjs/server";

// Types
import type {
  ManifestData,
  SearchQuery,
  PublishResponse,
  GetResourceResponse,
  SearchResultItem,
  SearchResponse,
  ErrorResponse,
  ErrorCode,
} from "@resourcexjs/server";

URL Builders

import { buildResourceUrl, buildSearchUrl } from "@resourcexjs/server";

const url = buildResourceUrl("https://registry.example.com", "hello:1.0.0");
// "https://registry.example.com/api/v1/resource/hello%3A1.0.0"

const searchUrl = buildSearchUrl("https://registry.example.com", {
  q: "prompt",
  limit: 10,
});
// "https://registry.example.com/api/v1/search?q=prompt&limit=10"

Error Handling

All error responses follow a consistent format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Error Codes

| Code | Status | Description | | -------------------- | ------ | ----------------------- | | LOCATOR_REQUIRED | 400 | Missing locator field | | MANIFEST_REQUIRED | 400 | Missing manifest file | | CONTENT_REQUIRED | 400 | Missing content file | | INVALID_MANIFEST | 400 | Invalid manifest format | | INVALID_LOCATOR | 400 | Invalid locator format | | RESOURCE_NOT_FOUND | 404 | Resource does not exist | | INTERNAL_ERROR | 500 | Internal server error |

Re-exports

For convenience, this package re-exports commonly used classes:

import { CASRegistry, FileSystemRXAStore, FileSystemRXMStore } from "@resourcexjs/server";

import type { RXAStore, RXMStore, Registry } from "@resourcexjs/server";

Storage Architecture

The server uses content-addressable storage (CAS) for efficient deduplication:

./data/
├── blobs/                        # Content-addressable blob storage
│   └── ab/
│       └── sha256:abcd1234...    # Archive data (tar.gz)
└── manifests/
    └── _local/                   # Resources stored on this server
        └── my-prompt/
            └── 1.0.0.json        # Manifest with digest reference

Note: The server stores resources without registry prefix. When a resource is published to registry.example.com/hello:1.0.0, it's stored as hello:1.0.0 on the server. The registry prefix is added by clients when they pull resources.

Related Packages

| Package | Description | | ---------------------------- | ------------------------------- | | resourcexjs | Client SDK | | @resourcexjs/core | Core primitives and CASRegistry | | @resourcexjs/node-provider | Node.js/Bun storage providers |

License

Apache-2.0