changelog.md for @push.rocks/smartregistry

2026-03-27 - 2.8.2 - fix(maven,tests)
handle Maven Basic auth and accept deploy-plugin metadata/checksum uploads while stabilizing npm CLI test cleanup
Validate Maven tokens from Basic auth credentials by extracting the password portion before token validation.
Return successful responses for PUT requests to checksum and maven-metadata endpoints so Maven deploy uploads do not fail when files are auto-generated.
Improve npm CLI integration test isolation and cleanup by using a temporary test directory, copying per-package .npmrc files, and cleaning stale published packages before test runs.
Tighten test teardown by destroying the registry explicitly and simplifying package/install fixture generation.
2026-03-24 - 2.8.1 - fix(registry)
align OCI and RubyGems API behavior and improve npm search result ordering
handle OCI version checks on /v2 and /v2/ endpoints
return RubyGems versions JSON in the expected flat array format and update unyank coverage to use the HTTP endpoint
prioritize exact and prefix matches in npm search results
update documentation to reflect full upstream proxy support
2026-03-24 - 2.8.0 - feat(core,storage,oci,registry-config)
add streaming response support and configurable registry URLs across protocols
Normalize SmartRegistry responses to ReadableStream bodies at the public API boundary and add stream helper utilities for buffers, JSON, and hashing
Add streaming storage accessors for OCI, npm, Maven, Cargo, Composer, PyPI, and RubyGems downloads to reduce in-memory buffering
Make per-protocol registryUrl configurable so CLI and integration tests can use correct host and port values
Refactor OCI blob uploads to persist chunks in storage during upload and clean up temporary chunk objects after completion or expiry
Update tests and storage integration to use the new stream-based response model and smartstorage backend
2025-12-03 - 2.7.0 - feat(upstream)
Add dynamic per-request upstream provider and integrate into registries
Introduce IUpstreamProvider and IUpstreamResolutionContext to resolve upstream configs per request.
Add StaticUpstreamProvider implementation for simple static upstream configurations.
Propagate dynamic upstream provider through SmartRegistry and wire into protocol handlers (npm, oci, maven, cargo, composer, pypi, rubygems).
Replace persistent per-protocol upstream instances with per-request resolution: registries now call provider.resolveUpstreamConfig(...) and instantiate protocol-specific Upstream when needed.
Add IRequestActor to core interfaces and pass actor context (userId, ip, userAgent, etc.) to upstream resolution and storage/auth hooks.
Update many protocol registries to accept an upstreamProvider instead of IProtocolUpstreamConfig and to attempt upstream fetches only when provider returns enabled config.
Add utilities and tests: test helpers to create registries with upstream provider, a tracking upstream provider helper, StaticUpstreamProvider tests and extensive upstream/provider integration tests.
Improve upstream interfaces and cache/fetch contexts (IUpstreamFetchContext includes actor) and add StaticUpstreamProvider class to upstream module.
2025-11-27 - 2.6.0 - feat(core)
Add core registry infrastructure: storage, auth, upstream cache, and protocol handlers
Introduce RegistryStorage: unified storage abstraction with hook support (before/after put/delete/get) and helpers for OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems paths and operations
Add DefaultAuthProvider and AuthManager: in-memory token store, UUID tokens for package protocols, OCI JWT creation/validation, token lifecycle (create/validate/revoke) and authorization checking
Add SmartRegistry orchestrator to initialize and route requests to protocol handlers (OCI, NPM, Maven, Cargo, Composer, PyPI, RubyGems)
Implement upstream subsystem: UpstreamCache (in-memory + optional S3 persistence), BaseUpstream with multi-upstream routing, scope rules, retries, TTLs, stale-while-revalidate and negative caching
Add circuit breaker implementation for upstream resilience with exponential backoff and per-upstream breakers
Add protocol implementations and helpers: NpmRegistry/NpmUpstream (packument/tarball handling and tarball URL rewriting), PypiRegistry (PEP 503/691 support, uploads, metadata), MavenRegistry (artifact/metadata handling and checksum generation), CargoRegistry (sparse index, publish/download/yank)
Utility exports and helpers: buffer helpers, plugins aggregator, path helpers, and various protocol-specific helper modules
2025-11-27 - 2.5.0 - feat(pypi,rubygems)
Add PyPI and RubyGems protocol implementations, upstream caching, and auth/storage improvements
Implemented full PyPI support (PEP 503 Simple API HTML, PEP 691 JSON API, legacy upload handling, name normalization, hash verification, content negotiation, package/file storage and metadata management).
Implemented RubyGems support (compact index, /versions, /info, /names endpoints, gem upload, yank/unyank, platform handling and file storage).
Expanded RegistryStorage with protocol-specific helpers for OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems (get/put/delete/list helpers, metadata handling, context-aware hooks).
Added AuthManager and DefaultAuthProvider improvements: unified token creation/validation for multiple protocols (npm, oci, maven, composer, cargo, pypi, rubygems) and OCI JWT support.
Added upstream infrastructure: BaseUpstream, UpstreamCache (S3-backed optional, stale-while-revalidate, negative caching), circuit breaker with retries/backoff and resilience defaults.
Added various protocol registries (NPM, Maven, Cargo, OCI, PyPI) with request routing, permission checks, and optional upstream proxying/caching.
2025-11-27 - 2.4.0 - feat(core)
Add pluggable auth providers, storage hooks, multi-upstream cache awareness, and PyPI/RubyGems protocol implementations
Introduce pluggable authentication: IAuthProvider interface and DefaultAuthProvider (in-memory) with OCI JWT support and UUID tokens.
AuthManager now accepts a custom provider and delegates all auth operations (authenticate, validateToken, create/revoke tokens, authorize, listUserTokens).
Add storage hooks (IStorageHooks) and hook contexts: beforePut/afterPut/afterGet/beforeDelete/afterDelete. RegistryStorage now supports hooks, context management (setContext/withContext) and invokes hooks around operations.
RegistryStorage expanded with many protocol-specific helper methods (OCI, NPM, Maven, Cargo, Composer, PyPI, RubyGems) and improved S3/SmartBucket integration.
Upstream improvements: BaseUpstream and UpstreamCache became multi-upstream aware (cache keys now include upstream URL), cache operations are async and support negative caching, stale-while-revalidate, ETag/metadata persistence, and S3-backed storage layer.
Circuit breaker, retry, resilience and scope-rule routing enhancements for upstreams; upstream fetch logic updated to prefer primary upstream for cache keys and background revalidation behavior.
SmartRegistry API extended to accept custom authProvider and storageHooks, and now wires RegistryStorage and AuthManager with those options. Core exports updated to expose auth and storage interfaces and DefaultAuthProvider.
Add full PyPI (PEP 503/691, upload API) and RubyGems (Compact Index, API v1, uploads/yank/unyank, specs endpoints) registry implementations with parsing, upload/download, metadata management and upstream proxying.
Add utility helpers: binary buffer helpers (toBuffer/isBinaryData), pypi and rubygems helper modules, and numerous protocol-specific helpers and tests referenced in readme.hints.
These changes are additive and designed to be backward compatible; bumping minor version.
2025-11-27 - 2.3.0 - feat(upstream)
Add upstream proxy/cache subsystem and integrate per-protocol upstreams
Introduce a complete upstream subsystem (BaseUpstream, UpstreamCache, CircuitBreaker) with caching, negative-cache, stale-while-revalidate, retries, exponential backoff and per-upstream circuit breakers.
Add upstream interfaces and defaults (ts/upstream/interfaces.upstream.ts) and export upstream utilities from ts/upstream/index.ts and root ts/index.ts.
Implement protocol-specific upstream clients for npm, pypi, maven, composer, cargo and rubygems (classes.*upstream.ts) to fetch metadata and artifacts from configured upstream registries.
Integrate upstream usage into registries: registries now accept an upstream config, attempt to fetch missing metadata/artifacts from upstreams, cache results locally, and expose destroy() to stop upstream resources.
Add SmartRequest and minimatch to dependencies and expose smartrequest/minimatch via ts/plugins.ts for HTTP requests and glob-based scope matching.
Update package.json to add @push.rocks/smartrequest and minimatch dependencies.
Various registry implementations updated to utilize upstreams (npm, pypi, maven, composer, cargo, rubygems, oci) including URL rewrites and caching behavior.
2025-11-27 - 2.2.3 - fix(tests)
Use unique test run IDs and add S3 cleanup in test helpers to avoid cross-run conflicts
Add generateTestRunId() helper in test/helpers/registry.ts to produce unique IDs for each test run
Update PyPI and Composer native CLI tests to use generated testPackageName / unauth-pkg- to avoid package name collisions between runs
Import smartbucket and add S3 bucket cleanup logic in test helpers to remove leftover objects between test runs
Improve test robustness by skipping upload-dependent checks when tools (twine/composer) are not available and logging outputs for debugging
2025-11-25 - 2.2.2 - fix(npm)
Replace console logging with structured Smartlog in NPM registry and silence RubyGems helper error logging
Replaced console.log calls with this.logger.log (Smartlog) in ts/npm/classes.npmregistry.ts for debug/info/success events
Converted console.error in NpmRegistry.handleSearch to structured logger.log('error', ...) including the error message
Removed console.error from ts/rubygems/helpers.rubygems.ts; gem metadata extraction failures are now handled silently by returning null
2025-11-25 - 2.2.1 - fix(core)
Normalize binary data handling across registries and add buffer helpers
Add core/helpers.buffer.ts with isBinaryData and toBuffer utilities to consistently handle Buffer, Uint8Array, string and object inputs.
Composer: accept Uint8Array uploads, convert to Buffer before ZIP extraction, SHA-1 calculation and storage.
PyPI: accept multipart file content as Buffer or Uint8Array and normalize to Buffer before processing and storage.
Maven: normalize artifact body input with toBuffer before validation and storage.
OCI: improve upload id generation by using substring for correct random length.
2025-11-25 - 2.2.0 - feat(core/registrystorage)
Persist OCI manifest content-type in sidecar and normalize manifest body handling
Add getOciManifestContentType(repository, digest) to read stored manifest Content-Type
Store manifest Content-Type in a .type sidecar file when putOciManifest is called
Update putOciManifest to persist both manifest data and its content type
OciRegistry now retrieves stored content type (with fallback to detectManifestContentType) when serving manifests
Add toBuffer helper in OciRegistry to consistently convert various request body forms to Buffer for digest calculation and uploads
2025-11-25 - 2.1.2 - fix(oci)
Prefer raw request body for content-addressable OCI operations and expose rawBody on request context
Add rawBody?: Buffer to IRequestContext to allow callers to provide the exact raw request bytes for digest calculation (falls back to body if absent).
OCI registry handlers now prefer context.rawBody over context.body for content-addressable operations (manifests, blobs, and blob uploads) to preserve exact bytes and ensure digest calculation matches client expectations.
Upload flow updates: upload init, PATCH (upload chunk) and PUT (complete upload) now pass rawBody when available.
2025-11-25 - 2.1.1 - fix(oci)
Preserve raw manifest bytes for digest calculation and handle string/JSON manifest bodies in OCI registry
Preserve the exact bytes of the manifest payload when computing the sha256 digest to comply with the OCI spec and avoid mismatches caused by re-serialization.
Accept string request bodies (converted using UTF-8) and treat already-parsed JSON objects by re-serializing as a fallback.
Keep existing content-type fallback logic while ensuring accurate digest calculation prior to storing manifests.
2025-11-25 - 2.1.0 - feat(oci)
Support configurable OCI token realm/service and centralize unauthorized responses
SmartRegistry now forwards optional ociTokens (realm and service) from auth configuration to OciRegistry when OCI is enabled
OciRegistry constructor accepts an optional ociTokens parameter and stores it for use in auth headers
Replaced repeated construction of WWW-Authenticate headers with createUnauthorizedResponse and createUnauthorizedHeadResponse helpers that use configured realm/service
Behavior is backwards-compatible: when ociTokens are not configured the registry falls back to the previous defaults (realm: <basePath>/v2/token, service: "registry")
2025-11-25 - 2.0.0 - BREAKING CHANGE(pypi,rubygems)
Revise PyPI and RubyGems handling: normalize error payloads, fix .gem parsing/packing, adjust PyPI JSON API and tests, and export smartarchive plugin
Rename error payload property from 'message' to 'error' in PyPI and RubyGems interfaces and responses; error responses are now returned as JSON objects (body: { error: ... }) instead of Buffer(JSON.stringify(...)).
RubyGems: treat .gem files as plain tar archives (not gzipped). Use metadata.gz and data.tar.gz correctly, switch packing helper to pack plain tar, and use zlib deflate for .rz gemspec data.
RubyGems registry: add legacy Marshal specs endpoint (specs.4.8.gz) and adjust versions handler invocation to accept request context.
PyPI: adopt PEP 691 style (files is an array of file objects) in tests and metadata; include requires_python in test package metadata; update JSON API path matching to the package-level '/{package}/json' style used by the handler.
Fix HTML escaping expectations in tests (requires_python values are HTML-escaped in attributes, e.g. '>=3.8').
Export smartarchive from plugins to enable archive helpers in core modules and helpers.
Update tests and internal code to match the new error shape and API/format behaviour.
2025-11-25 - 1.9.0 - feat(auth)
Implement HMAC-SHA256 OCI JWTs; enhance PyPI & RubyGems uploads and normalize responses
AuthManager: create and validate OCI JWTs signed with HMAC-SHA256 (header.payload.signature). Signature verification, exp/nbf checks and payload decoding implemented.
PyPI: improved Simple API handling (PEP-691 JSON responses returned as objects), Simple HTML responses updated, upload handling enhanced to support nested/flat multipart fields, verify hashes (sha256/md5/blake2b), store files and return 201 on success.
RubyGems: upload flow now attempts to extract gem metadata from the .gem binary when name/version are not provided, improved validation, and upload returns 201. Added extractGemMetadata helper.
OCI: centralized 401 response creation (including proper WWW-Authenticate header) and HEAD behavior fixed to return no body per HTTP spec.
SmartRegistry: use nullish coalescing for protocol basePath defaults to avoid falsy-value bugs when basePath is an empty string.
Tests and helpers: test expectations adjusted (Content-Type startsWith check for HTML, PEP-691 projects is an array), test helper switched to smartarchive for packaging.
Package.json: added devDependency @push.rocks/smartarchive and updated dev deps.
Various response normalization: avoid unnecessary Buffer.from() for already-serialized objects/strings and standardize status codes for create/upload endpoints (201).
2025-11-24 - 1.8.0 - feat(smarts3)
Add local smarts3 testing support and documentation
Added @push.rocks/smarts3 ^5.1.0 to devDependencies to enable a local S3-compatible test server.
Updated README with a new "Testing with smarts3" section including a Quick Start example and integration test commands.
Documented benefits and CI-friendly usage for running registry integration tests locally without cloud credentials.
2025-11-23 - 1.7.0 - feat(core)
Standardize S3 storage config using @tsclass/tsclass IS3Descriptor and wire it into RegistryStorage and plugins exports; update README and package dependencies.
Add @tsclass/tsclass dependency to package.json to provide a standardized IS3Descriptor for S3 configuration.
Export tsclass from ts/plugins.ts so plugin types are available to core modules.
Update IStorageConfig to extend plugins.tsclass.storage.IS3Descriptor, consolidating storage configuration typing.
Change RegistryStorage.init() to pass the storage config directly as an IS3Descriptor to SmartBucket (bucketName remains part of IStorageConfig).
Update README storage section with example config and mention IS3Descriptor integration.
2025-11-21 - 1.6.0 - feat(core)
Add PyPI and RubyGems registries, integrate into SmartRegistry, extend storage and auth
Introduce PyPI registry implementation with PEP 503 (Simple API) and PEP 691 (JSON API), legacy upload support, content negotiation and HTML/JSON generators (ts/pypi/*).
Introduce RubyGems registry implementation with Compact Index support, API v1 endpoints (upload, yank/unyank), versions/names files and helpers (ts/rubygems/*).
Wire PyPI and RubyGems into the main orchestrator: SmartRegistry now initializes, exposes and routes requests to pypi and rubygems handlers.
Extend RegistryStorage with PyPI and RubyGems storage helpers (metadata, simple index, package files, compact index files, gem files).
Extend AuthManager to support PyPI and RubyGems UUID token creation, validation and revocation and include them in unified token validation.
Add verification of client-provided hashes during PyPI uploads (SHA256 always calculated and verified; MD5 and Blake2b verified when provided) to prevent corrupted uploads.
Export new modules from library entry point (ts/index.ts) and add lightweight rubygems index file export.
Add helper utilities for PyPI and RubyGems (name normalization, HTML generation, hash calculations, compact index generation/parsing).
Update documentation hints/readme to reflect implementation status and configuration examples for pypi and rubygems.
2025-11-21 - 1.5.0 - feat(core)
Add PyPI and RubyGems protocol support, Cargo token management, and storage helpers
Extend core protocol types to include 'pypi' and 'rubygems' and add protocol config entries for pypi and rubygems.
Add PyPI storage methods for metadata, Simple API HTML/JSON indexes, package files, version listing and deletion in RegistryStorage.
Add Cargo-specific storage helpers (index paths, crate storage) and ensure Cargo registry initialization and endpoints are wired into SmartRegistry.
Extend AuthManager with Cargo, PyPI and RubyGems token creation, validation and revocation methods; update unified validateToken to check these token types.
Update test helpers to create Cargo tokens and return cargoToken from registry setup.
2025-11-21 - 1.4.1 - fix(devcontainer)
Simplify devcontainer configuration and rename container image
Rename Dev Container name to 'gitzone.universal' and set image to mcr.microsoft.com/devcontainers/universal:4.0.1-noble
Remove large inline comments and example 'build'/'features' blocks to simplify the devcontainer.json
2025-11-21 - 1.4.0 - feat(registrystorage)
Add deleteMavenMetadata to RegistryStorage and update Maven DELETE test to expect 204 No Content
Add deleteMavenMetadata(groupId, artifactId) to RegistryStorage to remove maven-metadata.xml.
Update Maven test to assert 204 No Content for DELETE responses (previously expected 200).
2025-11-21 - 1.3.1 - fix(maven)
Pass request path to Maven checksum handler so checksum files are resolved correctly
Call handleChecksumRequest with the full request path from MavenRegistry.handleRequest
Allows getChecksum to extract the checksum filename from the URL and fetch the correct checksum file from storage
Fixes 404s when requesting artifact checksum files (md5, sha1, sha256, sha512)
2025-11-21 - 1.3.0 - feat(core)
Add Cargo and Composer registries with storage, auth and helpers
Add Cargo registry implementation (ts/cargo) including index, publish, download, yank/unyank and search handlers
Add Composer registry implementation (ts/composer) including package upload/download, metadata, packages.json and helpers
Extend RegistryStorage with Cargo and Composer-specific storage helpers and path conventions
Extend AuthManager with Composer token creation/validation and unified token validation support
Wire SmartRegistry to initialize and route requests to cargo and composer handlers
Add adm-zip dependency and Composer ZIP parsing helpers (extractComposerJsonFromZip, sha1 calculation, version sorting)
Add tests for Cargo index path calculation and config handling
Export new modules from ts/index.ts and add module entry files for composer and cargo
2025-11-21 - 1.2.0 - feat(maven)
Add Maven registry protocol support (storage, auth, routing, interfaces, and exports)
Add Maven protocol to core types (TRegistryProtocol) and IRegistryConfig
SmartRegistry: initialize Maven registry when enabled, route requests to /maven, and expose it via getRegistry
RegistryStorage: implement Maven storage helpers (get/put/delete artifact, metadata, list versions) and path helpers
AuthManager: add UUID token creation/validation/revocation for Maven and integrate into unified validateToken/authorize flow
New ts/maven module: exports, interfaces and helpers for Maven coordinates, metadata, and search results
Add basic Cargo (crates.io) scaffolding: ts/cargo exports and Cargo interfaces
Update top-level ts/index.ts and package exports to include Maven (and cargo) modules
Tests/helpers updated to enable Maven in test registry and add Maven artifact/checksum helpers
2025-11-20 - 1.1.1 - fix(oci)
Improve OCI manifest permission response and tag handling: include WWW-Authenticate header on unauthorized manifest GETs, accept optional headers in manifest lookup, and persist tags as a unified tags.json mapping when pushing manifests.
getManifest now accepts an optional headers parameter for better request context handling.
Unauthorized GET manifest responses now include a WWW-Authenticate header with realm/service/scope to comply with OCI auth expectations.
PUT manifest logic no longer writes individual tag objects; it updates a consolidated oci/tags/{repository}/tags.json mapping using getTagsData and putObject.
Simplified tag update flow when pushing a manifest: tags[reference] = digest and persist tags.json.
2025-11-20 - 1.1.0 - feat(oci)
Support monolithic OCI blob uploads; add registry cleanup/destroy hooks; update tests and docs
OCI: Add monolithic upload handling in handleUploadInit — accept digest + body, verify digest, store blob and return 201 with Docker-Content-Digest and Location
OCI: Include Docker-Distribution-API-Version header in /v2/ version check response
Lifecycle: Persist upload session cleanup timer and provide destroy() to clear timers in OciRegistry
Orchestrator: Add destroy() to SmartRegistry to propagate cleanup to protocol handlers
Tests: Ensure test suites call registry.destroy() in postTask cleanup to prevent leaked timers/resources
Package metadata: bump @git.zone/tstest dev dependency and add packageManager field
Docs: Readme formatting and legal/trademark/company information updated
2025-11-20 - 1.0.2 - fix(scripts)
Increase tstest timeout from 30s to 240s in package.json test script
Extend the tstest CLI timeout in package.json from 30 seconds to 240 seconds to accommodate longer-running tests and reduce CI timeouts.
2025-11-20 - 1.0.1 - registry
Release 1.0.1 brings core registry features, multi-registry support, logging integration, and performance improvements to object listing. Also includes the initial project scaffold and CI/CD setup.
Add smartlog dependency and integrate structured logging into the NpmRegistry class for better runtime diagnostics and traceability.
Update smartbucket dependency to 4.3.0 and refactor listObjects for improved performance and efficiency when enumerating stored objects.
Implement multi-registry support (multiple iterations/refinements included: v2, v3) to allow managing and resolving packages across multiple registries.
Initial project setup: TypeScript project scaffold, development tooling, and CI/CD workflows for automated testing and publishing.
Co-authored-by: Ona no-reply@ona.com
Miscellaneous housekeeping and small updates (2025-11-19 — 2025-11-20): several commits with no substantive messages; grouped as non-functional/maintenance changes.