This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-auth-core.git
The following commit(s) were added to refs/heads/master by this push:
new b8c881c docs: add AGENTS.md and update README with build and API
notes (#26)
b8c881c is described below
commit b8c881c43f7657f2b0e1ffc9a2a8f15c5eb27c38
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 08:36:22 2026 +0200
docs: add AGENTS.md and update README with build and API notes (#26)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
README.md | 50 +++++++++++++++++++++++++++++----
3 files changed, 142 insertions(+), 5 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4970857
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,96 @@
+# Project Overview
+
+Apache Sling Auth Core (`org.apache.sling.auth.core`) is an OSGi bundle that
provides the Sling Authentication Service. It authenticates HTTP requests
against a JCR repository via a pluggable
`AuthenticationHandler`/`JakartaAuthenticationHandler` SPI. The core component
is `SlingAuthenticator`, which delegates to registered handlers matched by path
prefix. The bundle supports both legacy `javax.servlet` and Jakarta EE APIs.
OSGi components use `org.osgi.service.component.annotations` (DS [...]
+
+# Core Commands
+
+```bash
+# Build and package the OSGi bundle
+mvn package
+
+# Build skipping tests
+mvn package -DskipTests
+
+# Run full test suite
+mvn test
+
+# Run a single test class
+mvn test -Dtest=SlingAuthenticatorTest
+
+# Run a single test method
+mvn test -Dtest=SlingAuthenticatorTest#testSomeMethod
+
+# Verify (build + test + integration checks)
+mvn verify
+
+# Install to local Maven repo
+mvn install
+
+# Clean build artifacts
+mvn clean package
+```
+
+> No dev server — this is an OSGi bundle deployed into a Sling instance. See
https://sling.apache.org/documentation/development/sling.html for runtime setup.
+
+# Project Layout
+
+```
+pom.xml # Maven build descriptor; inherits
sling-bundle-parent
+bnd.bnd # OSGi bundle manifest overrides (optional
imports)
+src/
+ main/java/
+ org/apache/sling/auth/core/
+ AuthConstants.java # Shared constants
+ AuthUtil.java # Static utility methods for auth requests
+ AuthenticationSupport.java # Service interface for Sling engine
integration
+ spi/ # Public SPI: AuthenticationHandler,
AuthenticationInfo, etc.
+ impl/ # Internal OSGi components (not part of
public API)
+ SlingAuthenticator.java # Core DS component; main authentication logic
+ AuthenticationHandlersManager.java
+ AuthenticationRequirementsManager.java
+ LoginServlet.java
+ LogoutServlet.java
+ engine/ # Wrappers for Sling engine (Jakarta)
integration
+ hc/ # Felix Health Check integration
+ org/apache/sling/engine/auth/ # Deprecated legacy API (kept for
compatibility)
+ test/java/
+ org/apache/sling/auth/core/ # Unit tests mirror main package structure
+target/ # Build output (ignored by git)
+```
+
+# Development Patterns & Constraints
+
+- **Java 17**, no preview features.
+- **OSGi DS R7** annotations only (`org.osgi.service.component.annotations`).
Do not use Felix SCR annotations.
+- **No public API in `impl`** packages — `impl.*` is excluded from Javadoc and
must not be referenced externally.
+- The `spi` package is the stable public API; follow OSGi semantic versioning
when changing it (`package-info.java` carries `@Version`).
+- Both `javax.servlet` (legacy) and `jakarta.servlet` (Jakarta EE) APIs are
supported. New handler code should prefer the Jakarta variants
(`JakartaAuthenticationHandler`, etc.).
+- Optional OSGi imports declared in `bnd.bnd` (Felix HC, Sling Metrics, JCR) —
guard usage with null checks.
+- 4-space indentation, no tabs. Follow the existing code style (no
Spotless/Checkstyle plugin currently configured; match surrounding code).
+- Commit message prefix with Jira issue key: `SLING-XXXXX Description of
change`.
+
+# Git Workflow
+
+- Default branch: `master`.
+- Feature branches: create from `master`, name with Jira issue key (e.g.,
`SLING-12345-fix-auth-redirect`).
+- PRs are submitted via GitHub to the Apache mirror; upstream is
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-auth-core.git.
+- Commits must reference an ASF Jira issue. See
https://sling.apache.org/contributing.html for the full contribution process.
+- Do not push directly to `master`.
+
+# Testing Guidelines
+
+- **Framework**: JUnit 4 + Mockito + `org.apache.sling.testing.osgi-mock`
(JUnit 4 variant).
+- Test files live under `src/test/java/` mirroring the main source tree.
+- OSGi component tests use `OsgiContext` from `osgi-mock` to wire DS
components without a real OSGi runtime.
+- Run a single class: `mvn test -Dtest=ClassName`.
+- Run a single method: `mvn test -Dtest=ClassName#methodName`.
+- Coverage report: `mvn test jacoco:report` (if jacoco is inherited from
parent POM).
+- `impl` classes are internal — test them directly; no need to go through
public interfaces.
+
+# Gotchas
+
+- **Optional imports**: `javax.jcr`, Felix HC (`org.apache.felix.hc.api`), and
Sling Metrics (`org.apache.sling.commons.metrics`) are optional per `bnd.bnd`.
Code using them must handle `NoClassDefFoundError` or check service
availability at runtime.
+- **Dual servlet API**: Some classes have parallel `javax` and `jakarta`
variants. When modifying behavior, check both. The `engine/` subpackage bridges
the two.
+- **`sling-bundle-parent` POM** (version 66) governs dependency versions and
plugin config — do not re-declare managed versions unless overriding
intentionally.
+- `target/spotless-index` may appear even without explicit Spotless config —
it comes from the parent POM; run `mvn spotless:apply` if formatting checks
fail in CI.
+- The `org.apache.sling.engine.auth` package is a deprecated compatibility
shim — do not add new code there.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9a80b01
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+read @AGENTS.md
diff --git a/README.md b/README.md
index 6a9ae0b..a50e599 100644
--- a/README.md
+++ b/README.md
@@ -6,13 +6,53 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
-The Sling Authentication Service bundle provides the basic mechanisms to
authenticate HTTP requests with a JCR repository. The algorithms for extracting
authentication details from the requests is extensible by implementing an
AuthenticationHandler interface.
+The Sling Authentication Service bundle provides the basic mechanisms to
authenticate HTTP requests with a JCR repository. Authentication detail
extraction is extensible through the Authentication Handler SPI
(`AuthenticationHandler` and `JakartaAuthenticationHandler`).
+
+This module targets Java 17+ and OSGi Declarative Services (R7 annotations).
## Installation
This bundle should be installed into an OSGi framework together with the
Apache Sling Framework.
-Beyond Apache Sling it has the following requirements (bundles to be installed
in at least this version as well):
-- Apache Commons Codec 1.13.2
-- Apache Sling Commons Metrics 1.2.8 (starting with version 1.5.2)
-- io.dropwizard.metrics:metrics-core:3.2.6 (starting with version 1.5.2)
+Beyond Apache Sling it requires:
+- Apache Commons Codec 1.13+
+
+Optional integrations (if available in the runtime):
+- Apache Sling Commons Metrics 1.2.8+
+- Apache Felix Health Check API 2.0.0+
+- Apache Sling JCR API 2.0.4+
+
+## Build
+
+```bash
+mvn package
+```
+
+Useful commands:
+
+```bash
+mvn test
+mvn verify
+mvn package -DskipTests
+mvn clean package
+mvn install
+```
+
+## API and Runtime Notes
+
+- Supports both legacy `javax.servlet` (4.0.1) and Jakarta Servlet
(`jakarta.servlet` 6.1.0) based authentication handlers.
+- Internal implementation classes live in `org.apache.sling.auth.core.impl`;
public SPI is in `org.apache.sling.auth.core.spi`.
+- Metrics, health check, and some JCR-related packages are imported as
optional OSGi dependencies.
+
+## Project Structure
+```text
+pom.xml
+bnd.bnd
+src/
+ main/java/org/apache/sling/auth/core/
+ spi/
+ impl/
+ engine/
+ hc/
+ test/java/org/apache/sling/auth/core/
+```
