feat(core): Add Cargo and Composer registries with storage, auth and helpers

2025-11-21 09:13:02 +00:00
parent 92d27d8b15
commit 8d48627301
19 changed files with 1869 additions and 56 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,18 +1,21 @@
 # @push.rocks/smartregistry

-> 🚀 A composable TypeScript library implementing both **OCI Distribution Specification v1.1** and **NPM Registry API** for building unified container and package registries.
+> 🚀 A composable TypeScript library implementing **OCI Distribution Specification v1.1**, **NPM Registry API**, **Maven Repository**, **Cargo/crates.io Registry**, and **Composer/Packagist** for building unified container and package registries.

 ## ✨ Features

-### 🔄 Dual Protocol Support
+### 🔄 Multi-Protocol Support
 - **OCI Distribution Spec v1.1**: Full container registry with manifest/blob operations
 - **NPM Registry API**: Complete package registry with publish/install/search
+- **Maven Repository**: Java/JVM artifact management with POM support
+- **Cargo/crates.io Registry**: Rust crate registry with sparse HTTP protocol
+- **Composer/Packagist**: PHP package registry with Composer v2 protocol

 ### 🏗️ Unified Architecture
 - **Composable Design**: Core infrastructure with protocol plugins
 - **Shared Storage**: Cloud-agnostic S3-compatible backend ([@push.rocks/smartbucket](https://www.npmjs.com/package/@push.rocks/smartbucket))
- **Unified Authentication**: Scope-based permissions across both protocols
- **Path-based Routing**: `/oci/*` for containers, `/npm/*` for packages
+- **Unified Authentication**: Scope-based permissions across all protocols
+- **Path-based Routing**: `/oci/*` for containers, `/npm/*` for packages, `/maven/*` for Java artifacts, `/cargo/*` for Rust crates, `/composer/*` for PHP packages

 ### 🔐 Authentication & Authorization
 - NPM UUID tokens for package operations
@@ -35,6 +38,27 @@
 - ✅ Dist-tag management
 - ✅ Token management

+**Maven Features:**
+- ✅ Artifact upload/download
+- ✅ POM and metadata management
+- ✅ Snapshot and release versions
+- ✅ Checksum verification (MD5, SHA1)
+
+**Cargo Features:**
+- ✅ Crate publish (.crate files)
+- ✅ Sparse HTTP protocol (modern index)
+- ✅ Version yank/unyank
+- ✅ Dependency resolution
+- ✅ Search functionality
+
+**Composer Features:**
+- ✅ Package publish/download (ZIP format)
+- ✅ Composer v2 repository API
+- ✅ Package metadata (packages.json)
+- ✅ Version management
+- ✅ Dependency resolution
+- ✅ PSR-4/PSR-0 autoloading support
+
 ## 📥 Installation

 ```bash
@@ -78,6 +102,18 @@ const config: IRegistryConfig = {
    enabled: true,
    basePath: '/npm',
  },
+  maven: {
+    enabled: true,
+    basePath: '/maven',
+  },
+  cargo: {
+    enabled: true,
+    basePath: '/cargo',
+  },
+  composer: {
+    enabled: true,
+    basePath: '/composer',
+  },
 };

 const registry = new SmartRegistry(config);
@@ -212,6 +248,167 @@ const searchResults = await registry.handleRequest({
 });
 ```

+### 🦀 Cargo Registry (Rust Crates)
+
+```typescript
+// Get config.json (required for Cargo)
+const config = await registry.handleRequest({
+  method: 'GET',
+  path: '/cargo/config.json',
+  headers: {},
+  query: {},
+});
+
+// Get index file for a crate
+const index = await registry.handleRequest({
+  method: 'GET',
+  path: '/cargo/se/rd/serde',  // Path based on crate name length
+  headers: {},
+  query: {},
+});
+
+// Download a crate file
+const crateFile = await registry.handleRequest({
+  method: 'GET',
+  path: '/cargo/api/v1/crates/serde/1.0.0/download',
+  headers: {},
+  query: {},
+});
+
+// Publish a crate (binary format: [4 bytes JSON len][JSON][4 bytes crate len][.crate])
+const publishResponse = await registry.handleRequest({
+  method: 'PUT',
+  path: '/cargo/api/v1/crates/new',
+  headers: { 'Authorization': '<cargo-token>' },  // No "Bearer" prefix
+  query: {},
+  body: binaryPublishData,  // Length-prefixed binary format
+});
+
+// Yank a version (deprecate without deleting)
+const yankResponse = await registry.handleRequest({
+  method: 'DELETE',
+  path: '/cargo/api/v1/crates/my-crate/0.1.0/yank',
+  headers: { 'Authorization': '<cargo-token>' },
+  query: {},
+});
+
+// Unyank a version
+const unyankResponse = await registry.handleRequest({
+  method: 'PUT',
+  path: '/cargo/api/v1/crates/my-crate/0.1.0/unyank',
+  headers: { 'Authorization': '<cargo-token>' },
+  query: {},
+});
+
+// Search crates
+const search = await registry.handleRequest({
+  method: 'GET',
+  path: '/cargo/api/v1/crates',
+  headers: {},
+  query: { q: 'serde', per_page: '10' },
+});
+```
+
+**Using with Cargo CLI:**
+
+```toml
+# .cargo/config.toml
+[registries.myregistry]
+index = "sparse+https://registry.example.com/cargo/"
+
+[registries.myregistry.credential-provider]
+# Or use credentials directly:
+# [registries.myregistry]
+# token = "your-api-token"
+```
+
+```bash
+# Publish to custom registry
+cargo publish --registry=myregistry
+
+# Install from custom registry
+cargo install --registry=myregistry my-crate
+
+# Search custom registry
+cargo search --registry=myregistry tokio
+```
+
+### 🎼 Composer Registry (PHP Packages)
+
+```typescript
+// Get repository root (packages.json)
+const packagesJson = await registry.handleRequest({
+  method: 'GET',
+  path: '/composer/packages.json',
+  headers: {},
+  query: {},
+});
+
+// Get package metadata
+const metadata = await registry.handleRequest({
+  method: 'GET',
+  path: '/composer/p2/vendor/package.json',
+  headers: {},
+  query: {},
+});
+
+// Upload a package (ZIP with composer.json)
+const zipBuffer = await readFile('package.zip');
+const uploadResponse = await registry.handleRequest({
+  method: 'PUT',
+  path: '/composer/packages/vendor/package',
+  headers: { 'Authorization': `Bearer <composer-token>` },
+  query: {},
+  body: zipBuffer,
+});
+
+// Download package ZIP
+const download = await registry.handleRequest({
+  method: 'GET',
+  path: '/composer/dists/vendor/package/ref123.zip',
+  headers: {},
+  query: {},
+});
+
+// List all packages
+const list = await registry.handleRequest({
+  method: 'GET',
+  path: '/composer/packages/list.json',
+  headers: {},
+  query: {},
+});
+
+// Delete a specific version
+const deleteVersion = await registry.handleRequest({
+  method: 'DELETE',
+  path: '/composer/packages/vendor/package/1.0.0',
+  headers: { 'Authorization': `Bearer <composer-token>` },
+  query: {},
+});
+```
+
+**Using with Composer CLI:**
+
+```json
+// composer.json
+{
+  "repositories": [
+    {
+      "type": "composer",
+      "url": "https://registry.example.com/composer"
+    }
+  ]
+}
+```
+
+```bash
+# Install from custom registry
+composer require vendor/package
+
+# Update packages
+composer update
+```
+
 ### 🔐 Authentication

 ```typescript
@@ -374,6 +571,48 @@ NPM registry API compliant implementation.
 - `POST /-/npm/v1/tokens` - Create token
 - `PUT /-/package/{pkg}/dist-tags/{tag}` - Update tag

+#### CargoRegistry
+
+Cargo/crates.io registry with sparse HTTP protocol support.
+
+**Endpoints:**
+- `GET /config.json` - Registry configuration (sparse protocol)
+- `GET /index/{path}` - Index files (hierarchical structure)
+  - `/1/{name}` - 1-character crate names
+  - `/2/{name}` - 2-character crate names
+  - `/3/{c}/{name}` - 3-character crate names
+  - `/{p1}/{p2}/{name}` - 4+ character crate names
+- `PUT /api/v1/crates/new` - Publish crate (binary format)
+- `GET /api/v1/crates/{crate}/{version}/download` - Download .crate file
+- `DELETE /api/v1/crates/{crate}/{version}/yank` - Yank (deprecate) version
+- `PUT /api/v1/crates/{crate}/{version}/unyank` - Unyank version
+- `GET /api/v1/crates?q={query}` - Search crates
+
+**Index Format:**
+- Newline-delimited JSON (one line per version)
+- SHA256 checksums for .crate files
+- Yanked flag (keep files, mark unavailable)
+
+#### ComposerRegistry
+
+Composer v2 repository API compliant implementation.
+
+**Endpoints:**
+- `GET /packages.json` - Repository metadata and configuration
+- `GET /p2/{vendor}/{package}.json` - Package version metadata
+- `GET /p2/{vendor}/{package}~dev.json` - Dev versions metadata
+- `GET /packages/list.json` - List all packages
+- `GET /dists/{vendor}/{package}/{ref}.zip` - Download package ZIP
+- `PUT /packages/{vendor}/{package}` - Upload package (requires auth)
+- `DELETE /packages/{vendor}/{package}` - Delete entire package
+- `DELETE /packages/{vendor}/{package}/{version}` - Delete specific version
+
+**Package Format:**
+- ZIP archives with composer.json in root
+- SHA-1 checksums for verification
+- Version normalization (1.0.0 → 1.0.0.0)
+- PSR-4/PSR-0 autoloading configuration
+
 ## 🗄️ Storage Structure

 ```
@@ -385,16 +624,38 @@ bucket/
 │   │   └── {repository}/{digest}
 │   └── tags/
 │       └── {repository}/tags.json
-└── npm/
-    ├── packages/
-    │   ├── {name}/
-    │   │   ├── index.json          # Packument
-    │   │   └── {name}-{ver}.tgz    # Tarball
-    │   └── @{scope}/{name}/
-    │       ├── index.json
-    │       └── {name}-{ver}.tgz
-    └── users/
-        └── {username}.json
+├── npm/
+│   ├── packages/
+│   │   ├── {name}/
+│   │   │   ├── index.json          # Packument
+│   │   │   └── {name}-{ver}.tgz    # Tarball
+│   │   └── @{scope}/{name}/
+│   │       ├── index.json
+│   │       └── {name}-{ver}.tgz
+│   └── users/
+│       └── {username}.json
+├── maven/
+│   ├── artifacts/
+│   │   └── {group-path}/{artifact}/{version}/
+│   │       ├── {artifact}-{version}.jar
+│   │       ├── {artifact}-{version}.pom
+│   │       └── {artifact}-{version}.{ext}
+│   └── metadata/
+│       └── {group-path}/{artifact}/maven-metadata.xml
+├── cargo/
+│   ├── config.json                 # Registry configuration (sparse protocol)
+│   ├── index/                      # Hierarchical index structure
+│   │   ├── 1/{name}               # 1-char crate names (e.g., "a")
+│   │   ├── 2/{name}               # 2-char crate names (e.g., "io")
+│   │   ├── 3/{c}/{name}           # 3-char crate names (e.g., "3/a/axo")
+│   │   └── {p1}/{p2}/{name}       # 4+ char (e.g., "se/rd/serde")
+│   └── crates/
+│       └── {name}/{name}-{version}.crate  # Gzipped tar archives
+└── composer/
+    └── packages/
+        └── {vendor}/{package}/
+            ├── metadata.json       # All versions metadata
+            └── {reference}.zip     # Package ZIP files
 ```

 ## 🎯 Scope Format
@@ -408,9 +669,22 @@ Examples:
  npm:package:express:read          # Read express package
  npm:package:*:write               # Write any package
  npm:*:*:*                         # Full NPM access
+
  oci:repository:nginx:pull         # Pull nginx image
  oci:repository:*:push             # Push any image
  oci:*:*:*                         # Full OCI access
+
+  maven:artifact:com.example:read   # Read Maven artifact
+  maven:artifact:*:write            # Write any artifact
+  maven:*:*:*                       # Full Maven access
+
+  cargo:crate:serde:write           # Write serde crate
+  cargo:crate:*:read                # Read any crate
+  cargo:*:*:*                       # Full Cargo access
+
+  composer:package:vendor/package:read   # Read Composer package
+  composer:package:*:write          # Write any package
+  composer:*:*:*                    # Full Composer access
 ```

 ## 🔌 Integration Examples