feat(oci): Support monolithic OCI blob uploads; add registry cleanup/destroy hooks; update tests and docs

2025-11-20 19:46:34 +00:00
parent eca08604dc
commit 1c63b74bb8
10 changed files with 186 additions and 53 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,26 +1,26 @@
 # @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 both **OCI Distribution Specification v1.1** and **NPM Registry API** for building unified container and package registries.

-## Features
+## ✨ Features

-### Dual Protocol Support
+### 🔄 Dual Protocol Support
 - **OCI Distribution Spec v1.1**: Full container registry with manifest/blob operations
 - **NPM Registry API**: Complete package registry with publish/install/search

-### Unified Architecture
+### 🏗️ Unified Architecture
 - **Composable Design**: Core infrastructure with protocol plugins
- **Shared Storage**: Cloud-agnostic S3-compatible backend (@push.rocks/smartbucket)
+- **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

-### Authentication & Authorization
+### 🔐 Authentication & Authorization
 - NPM UUID tokens for package operations
 - OCI JWT tokens for container operations
 - Unified scope system: `npm:package:foo:write`, `oci:repository:bar:push`
 - Pluggable via async callbacks

-### Comprehensive Feature Set
+### 📦 Comprehensive Feature Set

 **OCI Features:**
 - ✅ Pull operations (manifests, blobs)
@@ -35,15 +35,17 @@ A composable TypeScript library implementing both OCI Distribution Specification
 - ✅ Dist-tag management
 - ✅ Token management

-## Installation
+## 📥 Installation

 ```bash
+# Using npm
 npm install @push.rocks/smartregistry
-# or
+
+# Using pnpm (recommended)
 pnpm add @push.rocks/smartregistry
 ```

-## Quick Start
+## 🚀 Quick Start

 ```typescript
 import { SmartRegistry, IRegistryConfig } from '@push.rocks/smartregistry';
@@ -90,7 +92,7 @@ const response = await registry.handleRequest({
 });
 ```

-## Architecture
+## 🏛️ Architecture

 ### Directory Structure

@@ -126,9 +128,9 @@ Path-based routing
    S3-compatible backend
 ```

-## Usage Examples
+## 💡 Usage Examples

-### OCI Registry (Container Images)
+### 🐳 OCI Registry (Container Images)

 ```typescript
 // Pull an image
@@ -160,7 +162,7 @@ await registry.handleRequest({
 });
 ```

-### NPM Registry (Packages)
+### 📦 NPM Registry (Packages)

 ```typescript
 // Install a package (get metadata)
@@ -210,10 +212,10 @@ const searchResults = await registry.handleRequest({
 });
 ```

-### Authentication
+### 🔐 Authentication

 ```typescript
-// NPM Login
+// Get auth manager instance
 const authManager = registry.getAuthManager();

 // Authenticate user
@@ -243,7 +245,7 @@ const canWrite = await authManager.authorize(
 );
 ```

-## Configuration
+## ⚙️ Configuration

 ### Storage Configuration

@@ -300,13 +302,13 @@ npm?: {
 }
 ```

-## API Reference
+## 📚 API Reference

 ### Core Classes

 #### SmartRegistry

-Main orchestrator class.
+Main orchestrator class that routes requests to appropriate protocol handlers.

 **Methods:**
 - `init()` - Initialize the registry
@@ -317,7 +319,7 @@ Main orchestrator class.

 #### RegistryStorage

-Unified storage abstraction.
+Unified storage abstraction for both OCI and NPM content.

 **OCI Methods:**
 - `getOciBlob(digest)` - Get blob
@@ -333,7 +335,7 @@ Unified storage abstraction.

 #### AuthManager

-Unified authentication manager.
+Unified authentication manager supporting both NPM and OCI authentication schemes.

 **Methods:**
 - `authenticate(credentials)` - Validate user credentials
@@ -346,17 +348,22 @@ Unified authentication manager.

 #### OciRegistry

+OCI Distribution Specification v1.1 compliant registry.
+
 **Endpoints:**
 - `GET /v2/` - Version check
 - `GET /v2/{name}/manifests/{ref}` - Get manifest
 - `PUT /v2/{name}/manifests/{ref}` - Push manifest
 - `GET /v2/{name}/blobs/{digest}` - Get blob
 - `POST /v2/{name}/blobs/uploads/` - Initiate upload
+- `PUT /v2/{name}/blobs/uploads/{uuid}` - Complete upload
 - `GET /v2/{name}/tags/list` - List tags
 - `GET /v2/{name}/referrers/{digest}` - Get referrers

 #### NpmRegistry

+NPM registry API compliant implementation.
+
 **Endpoints:**
 - `GET /{package}` - Get package metadata
 - `PUT /{package}` - Publish package
@@ -367,7 +374,7 @@ Unified authentication manager.
 - `POST /-/npm/v1/tokens` - Create token
 - `PUT /-/package/{pkg}/dist-tags/{tag}` - Update tag

-## Storage Structure
+## 🗄️ Storage Structure

 ```
 bucket/
@@ -390,7 +397,7 @@ bucket/
        └── {username}.json
 ```

-## Scope Format
+## 🎯 Scope Format

 Unified scope format across protocols:

@@ -400,13 +407,13 @@ Unified scope format across protocols:
 Examples:
  npm:package:express:read          # Read express package
  npm:package:*:write               # Write any package
-  npm:*:*                           # Full NPM access
+  npm:*:*:*                         # Full NPM access
  oci:repository:nginx:pull         # Pull nginx image
  oci:repository:*:push             # Push any image
-  oci:*:*                           # Full OCI access
+  oci:*:*:*                         # Full OCI access
 ```

-## Integration Examples
+## 🔌 Integration Examples

 ### Express Server

@@ -446,7 +453,7 @@ app.all('*', async (req, res) => {
 app.listen(5000);
 ```

-## Development
+## 🛠️ Development

 ```bash
 # Install dependencies
@@ -459,10 +466,21 @@ pnpm run build
 pnpm test
 ```

-## License
+## License and Legal Information

-MIT
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.

-## Contributing
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

-Contributions welcome! Please see the repository for guidelines.
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+
+### Company Information
+
+Task Venture Capital GmbH
+Registered at District court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.