(sling-org-apache-sling-distribution-core) branch master updated: Add CLAUDE.md

[cs...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cschneider pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-distribution-core.git


The following commit(s) were added to refs/heads/master by this push:
     new 6c8abf52 Add CLAUDE.md
6c8abf52 is described below

commit 6c8abf526ee540f614f6f5b30ec08d16d2ef52d9
Author: Christian Schneider <cs...@adobe.com>
AuthorDate: Mon Jun 29 20:25:22 2026 +0200

    Add CLAUDE.md
---
 CLAUDE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..64d5f8ad
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,51 @@
+# Apache Sling Distribution Core
+
+## Overview
+
+This bundle provides the concrete infrastructure for the Apache Sling Content Distribution (SCD) module: agent management, queue implementations, content serialization (FileVault / Jackrabbit Vault), HTTP transport, and OSGi servlet endpoints. It implements the API contracts defined in `sling-org-apache-sling-distribution-api` and serves as the common runtime layer that journal-based and job-based distribution implementations build on top of.
+
+## Tech Stack
+
+- Java 8, OSGi bundle (bnd-maven-plugin, `sling-bundle-parent` v66)
+- Apache Jackrabbit / Jackrabbit Vault 3.6.4 for content serialization
+- Apache HttpComponents 4.x for HTTP transport
+- OSGi DS annotations (`@Component`, `@Reference`)
+- Testing: JUnit 4, Mockito 4, Sling OSGi Mock, Sling Mock (Oak-backed), Pax Exam for integration tests
+
+## Build & Test Commands
+
+```
+mvn clean install                      # build, unit tests (excludes *IT.java)
+mvn verify                             # build + integration tests (Pax Exam)
+mvn test -Dtest=SomeUnitTest           # single unit test class
+mvn failsafe:integration-test -Dit.test=SomeIT   # single IT class
+```
+
+Integration tests (`*IT.java`) are excluded from `maven-surefire-plugin` and run via `maven-failsafe-plugin`. They use Pax Exam and spin up an OSGi container, so they are slow and require network access to download bundles.
+
+## Architecture
+
+Key packages under `org.apache.sling.distribution`:
+
+| Package | Purpose |
+|---|---|
+| `impl` | `DefaultDistributor` — main entry point; orchestrates agent lookup and dispatch |
+| `agent.spi` / `agent.impl` | `DistributionAgent` SPI and concrete agent types (Simple, Sync, Forward) |
+| `packaging` / `packaging.impl` | `DistributionPackage`, `DistributionPackageBuilder`, `DistributionPackageInfo`; Vault-based serialization under `impl` |
+| `serialization` / `serialization.impl.vlt` | `DistributionContentSerializer` and FileVault implementation |
+| `queue` / `queue.spi` / `queue.impl` | `DistributionQueue` SPI; job-handling, resource-backed, and simple (in-memory) queue impls |
+| `transport` / `transport.impl` | HTTP transport; `DistributionTransportHandler` for pulling/pushing packages over HTTP |
+| `trigger` / `trigger.impl` | `DistributionTrigger` SPI; scheduled, JCR event-based, and remote-event-based triggers |
+| `servlet` | Sling servlet endpoints for agent status, queue, log, import, export, and trigger management |
+| `monitor` | Felix HealthCheck integration (`DistributionQueueHealthCheck`) |
+| `resources` | Virtual Sling resource types for agent/queue/log REST representations |
+
+Data flow: `DefaultDistributor` → resolves `DistributionAgent` OSGi service → agent calls `DistributionPackageBuilder` to serialize JCR content → places `DistributionQueueItem` in a `DistributionQueue` → transport sends it.
+
+## Conventions & Gotchas
+
+- The `agent.spi` and `queue.spi` sub-packages are SPI (stable, versioned); `*.impl` packages are internal and not exported.
+- There are **three queue implementations**: job-handling (backed by Sling Jobs), resource-backed (JCR nodes), and simple (in-memory). Journal-based distribution (sling-org-apache-sling-distribution-journal) replaces these with a journal-aware queue; don't conflate the two.
+- Integration tests annotated with `*IT.java` require the full OSGi container; running them locally may fail if artifact resolution is blocked by a corporate Maven proxy. Run `mvn verify -Pit` (or without `-P`, since failsafe binds to `verify` phase automatically).
+- `bnd.bnd` at the repo root controls OSGi bundle headers in addition to the POM; check both when changing exported packages.
+- Jackrabbit Vault serialization produces binary-less packages by default in the journal distribution path — binaries are stored in the shared blob store and referenced by ID, not inlined.