{"id":51351296,"url":"https://github.com/bright-room/aktive-storage","last_synced_at":"2026-07-02T16:06:52.668Z","repository":{"id":364842794,"uuid":"1269357685","full_name":"bright-room/aktive-storage","owner":"bright-room","description":"Framework-agnostic file attachment toolkit for the JVM — a Kotlin core with pluggable storage, ORM, and image-variant adapters.","archived":false,"fork":false,"pushed_at":"2026-06-14T17:49:19.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T19:20:21.486Z","etag":null,"topics":["coroutines","file-attachment","jvm","kotlin","library","object-storage"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bright-room.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T16:03:03.000Z","updated_at":"2026-06-14T17:49:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bright-room/aktive-storage","commit_stats":null,"previous_names":["bright-room/aktive-storage"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bright-room/aktive-storage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bright-room%2Faktive-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bright-room%2Faktive-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bright-room%2Faktive-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bright-room%2Faktive-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bright-room","download_url":"https://codeload.github.com/bright-room/aktive-storage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bright-room%2Faktive-storage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35053610,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coroutines","file-attachment","jvm","kotlin","library","object-storage"],"created_at":"2026-07-02T16:06:49.895Z","updated_at":"2026-07-02T16:06:52.567Z","avatar_url":"https://github.com/bright-room.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# aktive-storage\n\n[![Maven Central](https://img.shields.io/maven-central/v/net.bright-room.aktive-storage/core?label=Maven%20Central)](https://central.sonatype.com/namespace/net.bright-room.aktive-storage)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![CI](https://github.com/bright-room/aktive-storage/actions/workflows/ci.yml/badge.svg)](https://github.com/bright-room/aktive-storage/actions/workflows/ci.yml)\n\n**English** | [日本語](README.ja.md)\n\nFramework-agnostic file attachment toolkit for the JVM — a Kotlin core with pluggable storage, ORM, and image-variant adapters. Inspired by Rails' ActiveStorage, but free of any web-framework or ORM lock-in.\n\n## Modules\n\n| Module | Coordinate | Description |\n|---|---|---|\n| Core | `net.bright-room.aktive-storage:core` | attach/detach, signed delivery, storage \u0026 metadata ports |\n| Filesystem | `net.bright-room.aktive-storage:storage-fs` | local filesystem `StorageService` (proxy delivery) |\n| S3 | `net.bright-room.aktive-storage:storage-s3` | AWS S3 `StorageService` (presigned-redirect delivery) |\n| Exposed (JDBC) | `net.bright-room.aktive-storage:metadata-exposed-jdbc` | `MetadataStore` backed by JetBrains Exposed |\n| BOM | `net.bright-room.aktive-storage:bom` | version alignment for all modules |\n\n## Requirements\n\n- JDK 21+\n\n## Install\n\nGradle (Kotlin DSL) — use the BOM to align versions:\n\n```kotlin\ndependencies {\n    implementation(platform(\"net.bright-room.aktive-storage:bom:0.0.1\"))\n    implementation(\"net.bright-room.aktive-storage:core\")\n    implementation(\"net.bright-room.aktive-storage:storage-fs\")\n    implementation(\"net.bright-room.aktive-storage:metadata-exposed-jdbc\")\n\n    // a JDBC driver for the metadata store (H2 shown for a quick try)\n    runtimeOnly(\"com.h2database:h2:2.4.240\")\n}\n```\n\n## Quickstart\n\n```kotlin\nimport kotlinx.coroutines.runBlocking\nimport kotlinx.io.files.Path\nimport net.brightroom.aktivestorage.AktiveStorage\nimport net.brightroom.aktivestorage.ContentSource\nimport net.brightroom.aktivestorage.Delivery\nimport net.brightroom.aktivestorage.HmacReferenceSigner\nimport net.brightroom.aktivestorage.RecordRef\nimport net.brightroom.aktivestorage.metadata.exposed.ExposedMetadataStore\nimport net.brightroom.aktivestorage.storage.fs.FilesystemStorageService\nimport org.jetbrains.exposed.v1.jdbc.Database\nimport kotlin.time.Duration.Companion.minutes\n\nfun main() = runBlocking {\n    // Wire up: filesystem storage + Exposed metadata + HMAC signer for delivery tokens\n    val metadata = ExposedMetadataStore(\n        Database.connect(\"jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1\", driver = \"org.h2.Driver\"),\n    ).also { it.createSchema() }\n\n    val storage = AktiveStorage(\n        service = FilesystemStorageService(Path(\"uploads\")),\n        metadata = metadata,\n        signer = HmacReferenceSigner(\"change-me-in-production\".encodeToByteArray()),\n    )\n\n    // Attach bytes to a record — e.g. User#42's \"avatar\"\n    val attachment = storage.attach(\n        RecordRef(\"User\", \"42\"),\n        \"avatar\",\n        ContentSource.ofBytes(\"a.png\", \"image/png\", \"the-bytes\".encodeToByteArray()),\n    )\n\n    // Issue a signed, time-limited delivery token, then resolve how to serve it\n    val blob = storage.blobOf(attachment)!!\n    val token = storage.signedReference(blob, 5.minutes)\n    when (val delivery = storage.resolveForDelivery(token)) {\n        is Delivery.Redirect -\u003e println(\"302 redirect -\u003e ${delivery.url.value}\") // presigned services (S3)\n        is Delivery.Proxy -\u003e println(\"proxy ${delivery.blob.byteSize} bytes\")     // filesystem\n        null -\u003e println(\"invalid or expired token\")\n    }\n}\n```\n\n`storage-s3` swaps the filesystem service for S3 and serves files via presigned redirects instead of proxying. See [the integration test](integration-tests/src/test/kotlin/net/brightroom/aktivestorage/it/EndToEndIT.kt) for a full S3 + PostgreSQL example.\n\n## Versioning\n\naktive-storage follows semantic versioning with pre-1.0 semantics:\n\n- **`0.x` does not guarantee API stability.** A minor bump (`0.MINOR.0`) may include breaking changes; a patch bump (`0.0.PATCH`) is backward-compatible fixes only. The public API stabilizes at `1.0`.\n- The public ABI is guarded in CI by the [Kotlin Gradle plugin's ABI validation](https://kotlinlang.org/docs/gradle-binary-compatibility-validation.html) to catch *unintended* breaks. Intentional changes regenerate the `api/*.api` dumps (`./gradlew updateKotlinAbi`) and bump the minor version.\n\nReleases are published to Maven Central on tag push — see [Releasing](docs/RELEASING.md).\n\n## License\n\n[Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbright-room%2Faktive-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbright-room%2Faktive-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbright-room%2Faktive-storage/lists"}