Development Guide¶

Table of Contents¶

Getting Started
Project Structure
Building
Testing
Code Conventions
Extending the Extension
Debugging
Contributing

Getting Started¶

Prerequisites¶

Java: JDK 21 or higher
Maven: 3.9.0 or higher
IDE: IntelliJ IDEA, Eclipse, or VS Code with Java extensions
Docker: For integration testing (optional)
Git: For version control

Clone the Repository¶

git clone https://github.com/FortuneN/kete.git
cd kete

IDE Setup¶

IntelliJ IDEA¶

Open the project: File → Open → Select pom.xml
Wait for Maven import to Complete
Set JDK: File → Project Structure → Project SDK → 21
Enable annotation processing: Settings → Build → Compiler → Annotation Processors → Enable

VS Code¶

Install extensions:
Extension Pack for Java
Maven for Java
Open folder
Select Java 21 in status bar
Maven will auto-import dependencies

Eclipse¶

Import project: File → Import → Maven → Existing Maven Projects
Select project directory
Set JDK: Properties → Java Build Path → Libraries → Add Library → JRE System Library

Project Structure¶

kete/
├── src/
│   ├── main/
│   │   ├── java/io/github/fortunen/kete/
│   │   │   ├── CertificateLoader.java            # Abstract certificate loader
│   │   │   ├── Component.java                    # DI annotation
│   │   │   ├── Configuration.java                # Config parser
│   │   │   ├── Constants.java                    # Constants
│   │   │   ├── Destination.java                  # Abstract destination
│   │   │   ├── DestinationConfig.java            # Destination config base
│   │   │   ├── DestinationPooledObjectFactory.java # Destination pooling
│   │   │   ├── EventMessage.java                 # Event data record
│   │   │   ├── Matcher.java                      # Abstract matcher
│   │   │   ├── MatchMode.java                    # Match mode enum
│   │   │   ├── OAuthMaterial.java                # OAuth configuration
│   │   │   ├── Provider.java                     # Event handler
│   │   │   ├── ProviderFactory.java              # Lifecycle mgmt
│   │   │   ├── Route.java                        # Route configuration
│   │   │   ├── Serializer.java                   # Abstract serializer
│   │   │   ├── SerializerRoutes.java             # Serializer-routes mapping
│   │   │   ├── TlsMaterial.java                  # TLS configuration
│   │   │   ├── certificateloaders/               # Certificate loader implementations
│   │   │   │   ├── DerFileBase64CertificateLoader.java
│   │   │   │   ├── DerFilePathCertificateLoader.java
│   │   │   │   ├── JksFileBase64CertificateLoader.java
│   │   │   │   ├── JksFilePathCertificateLoader.java
│   │   │   │   ├── PemFileBase64CertificateLoader.java
│   │   │   │   ├── PemFilePathCertificateLoader.java
│   │   │   │   ├── PemFileTextCertificateLoader.java
│   │   │   │   ├── Pkcs12FileBase64CertificateLoader.java
│   │   │   │   ├── Pkcs12FilePathCertificateLoader.java
│   │   │   │   ├── Pkcs7FileBase64CertificateLoader.java
│   │   │   │   └── Pkcs7FilePathCertificateLoader.java
│   │   │   ├── destinations/                     # Destination implementations
│   │   │   │   ├── Amqp091Destination.java
│   │   │   │   ├── Amqp091DestinationConfig.java
│   │   │   │   ├── Amqp1Destination.java
│   │   │   │   ├── Amqp1DestinationConfig.java
│   │   │   │   ├── HttpDestination.java
│   │   │   │   ├── HttpDestinationConfig.java
│   │   │   │   ├── KafkaDestination.java
│   │   │   │   ├── KafkaDestinationConfig.java
│   │   │   │   ├── Mqtt3Destination.java
│   │   │   │   ├── Mqtt3DestinationConfig.java
│   │   │   │   ├── Mqtt5Destination.java
│   │   │   │   └── Mqtt5DestinationConfig.java
│   │   │   ├── matchers/                         # Matcher implementations
│   │   │   │   ├── GlobMatcher.java
│   │   │   │   ├── ListMatcher.java
│   │   │   │   ├── RegexMatcher.java
│   │   │   │   └── SqlMatcher.java
│   │   │   ├── serializers/                      # Serializer implementations
│   │   │   │   ├── CborSerializer.java
│   │   │   │   ├── CsvSerializer.java
│   │   │   │   ├── JsonSerializer.java
│   │   │   │   ├── PropertiesSerializer.java
│   │   │   │   ├── SmileSerializer.java
│   │   │   │   ├── TomlSerializer.java
│   │   │   │   ├── XmlSerializer.java
│   │   │   │   └── YamlSerializer.java
│   │   │   └── utils/                            # Utility classes
│   │   │       ├── CertificateUtils.java
│   │   │       ├── ConfigurationUtils.java
│   │   │       ├── DestinationUtils.java
│   │   │       ├── FileUtils.java
│   │   │       ├── IocUtils.java
│   │   │       ├── MatcherUtils.java
│   │   │       ├── RetryUtils.java
│   │   │       ├── RouteUtils.java
│   │   │       ├── SerializerUtils.java
│   │   │       ├── TemplateUtils.java
│   │   │       └── ValidationUtils.java
│   │   └── resources/
│   │       └── META-INF/services/
│   │           └── org.keycloak.events.EventListenerProviderFactory
│   └── tests/
│       ├── java/io/github/fortunen/kete/
│       │   ├── certificateloaders/               # Certificate loader tests
│       │   ├── destinationpooledobjectfactory/   # Pool factory tests
│       │   ├── destinations/                     # Destination tests
│       │   ├── e2e/                              # End-to-end tests
│       │   ├── eventmessage/                     # EventMessage tests
│       │   ├── matchers/                         # Matcher tests
│       │   ├── oauthmaterial/                    # OAuth tests
│       │   ├── provider/                         # Provider tests
│       │   ├── providerfactory/                  # Factory tests
│       │   ├── route/                            # Route tests
│       │   ├── serializers/                      # Serializer tests
│       │   ├── tlsmaterial/                      # TLS tests
│       │   └── utils/                            # Utility tests
│       └── resources/
│           └── testcontainers.properties         # Test config
├── docs/                                         # Documentation
├── Dockerfile                                    # Container image
├── pom.xml                                       # Maven config
└── README.md                                     # Main documentation

Key Files¶

File	Purpose
`pom.xml`	Maven dependencies and build configuration
`META-INF/services/...`	SPI registration for Keycloak
`Component.java`	Custom DI annotation for component discovery
`ProviderFactory.java`	Extension entry point and lifecycle management
`Provider.java`	Event processing logic
`Route.java`	Route configuration with matchers, serializer, destination
`DestinationConfig.java`	Base class for destination configurations
`TlsMaterial.java`	TLS/SSL configuration builder

Building¶

Dependency Shading (Critical)¶

All runtime dependencies are shade-relocated to prevent classpath conflicts with Keycloak's internal libraries.

Why this matters: - Keycloak bundles Guava, Jackson, Netty, Apache Commons, etc. - Different Keycloak versions use different library versions - Without shading: NoSuchMethodError, ClassNotFoundException at runtime - With shading: Extension works across Keycloak 25.x → 26.x+ without recompilation

What is shaded: Every dependency without <scope>provided</scope> or <scope>test</scope> is relocated under io.github.fortunen.kete.shaded.*

See: pom.xml → maven-shade-plugin → <relocations> section (17 libraries relocated)

NEVER: Add runtime dependencies without corresponding <relocation> entries.

Full Build¶

mvn clean package

Output: target/kete.jar (shaded JAR with all dependencies isolated)

Skip Tests¶

mvn clean package -DskipTests

Clean Build¶

mvn clean

Build with Coverage¶

mvn clean test jacoco:report

Output: target/site/jacoco/index.html

Verify Build¶

mvn verify

Runs all tests and creates the final JAR.

Testing¶

Unit Tests¶

Run all unit tests:

mvn test

Run specific test:

mvn test -Dtest=Provider_onEvent

Run tests in a package:

mvn test -Dtest=io.github.fortunen.kete.provider.*

Test Naming Convention¶

Tests are organized following the one-method-per-file pattern:

Directory structure: {classname}/{methodName}Tests.java

Examples: - provider/constructorTests.java - Tests Provider constructor - provider/onEventTests.java - Tests Provider.onEvent() method - providerfactory/closeTests.java - Tests ProviderFactory.close() method

Method naming: should{ExpectedBehavior}[When{Condition}]

Examples: - shouldReturnTrueWhenEventMatches() - shouldThrowWhenConfigurationIsNull() - shouldSerializeEventToJson()

Test Structure (AAA Pattern)¶

All tests use the Arrange-Act-Assert pattern with required comments:

@Test
public void shouldDoSomethingWhenConditionMet() {

    // arrange

    var instance = new ClassUnderTest();
    var input = "test-input";

    // act

    var result = instance.methodUnderTest(input);

    // assert

    assertThat(result).isNotNull();
    assertThat(result).isEqualTo("expected");
}

Mocking with Mockito¶

Use mock() method (not @Mock annotations):

@Test
public void shouldSendMessageToDestination() {

    // arrange

    var destination = mock(Destination.class);
    when(destination.accept("LOGIN")).thenReturn(true);

    // act

    route.send(message);

    // assert

    verify(destination).sendMessage(any(EventMessage.class));
}

Exception Testing¶

Use catchThrowable() with chained assertions:

@Test
public void shouldThrowWhenConfigurationIsNull() {

    // arrange

    var instance = new ClassUnderTest();

    // act

    var thrown = catchThrowable(() -> instance.initialize(null));

    // assert

    assertThat(thrown)
        .isInstanceOf(IllegalStateException.class)
        .hasMessage("configuration is required");
}

Integration Tests¶

Integration tests use Testcontainers for Kafka, RabbitMQ, etc.:

# Requires Docker
mvn verify

Tests automatically start containers, run tests, and clean up.

Coverage Reports¶

mvn clean test jacoco:report
open target/site/jacoco/index.html  # macOS/Linux
start target/site/jacoco/index.html # Windows

Current Coverage: ~90% (check latest report)

Code Conventions¶

Java Style¶

Indentation: Tabs, no spaces
Line Length: None
Braces: K&R style (opening brace on same line)
Naming:
Classes: PascalCase
Methods: camelCase
Constants: UPPER_SNAKE_CASE
Packages: lowercase

Code Example¶

public class MyComponent {

    private static final String CONSTANT_VALUE = "value";

    private final Logger logger;
    private final String configuration;

    public MyComponent(Logger logger, String configuration) {
        this.logger = Objects.requireNonNull(logger, "logger is required");
        this.configuration = Objects.requireNonNull(configuration, "configuration is required");
    }

    public void processEvent(Event event) {
        try {
            // Process event
        } catch (Exception exception) {
            logger.log(Level.WARNING, "Failed to process event", exception);
        }
    }
}

Documentation¶

No JavaDoc: Code should be self-documenting through clear naming
Inline Comments: Minimal - only for truly complex logic
README: Keep README.md up to date
Developer Docs: Update docs/ when adding features

Extending the Extension¶

Adding a New Destination¶

See Extending KETE for comprehensive details.

Quick Steps:

Create config class extending DestinationConfig
Create destination class extending Destination<TConfig>
Add @Component(name = "xxx") annotation
Implement doInitialize() and doSend(EventMessage)
Add tests following the test patterns

Adding a New Serializer¶

See Extending KETE for comprehensive details.

Quick Steps:

Create class extending Serializer
Add @Component(name = "xxx", scope = Component.SINGLETON)
Set contentType in constructor
Implement serialize(Event) and serialize(AdminEvent)
Add tests

Adding a New Matcher¶

See Extending KETE for comprehensive details.

Quick Steps:

Create class extending Matcher
Add @Component(name = "xxx") annotation
Implement initialize() and matches(String)
Add tests

Debugging¶

Local Debugging with IDE¶

Build the extension:
```
mvn clean package
```

Copy to local Keycloak:

cp target/kete.jar ~/keycloak-26.5.0/providers/

Start Keycloak in debug mode:

export KC_LOG_LEVEL=DEBUG
export JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
~/keycloak-26.5.0/bin/kc.sh start-dev

Attach debugger:
IntelliJ: Run → Attach to Process → Select Keycloak
VS Code: Add configuration:

{
    "type": "java",
    "name": "Attach to Keycloak",
    "request": "attach",
    "hostName": "localhost",
    "port": 5005
}

Set breakpoints in your code
Trigger events in Keycloak (login, logout, etc.)

Docker Debugging¶

Build Docker image with debug enabled:

FROM quay.io/keycloak/keycloak:26.5.0
COPY target/kete.jar /opt/keycloak/providers/
ENV JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
RUN /opt/keycloak/bin/kc.sh build

Run with port exposed:

docker run -p 8080:8080 -p 5005:5005 keycloak-debug start-dev

Attach debugger to localhost:5005

Logging¶

Enable detailed logging:

export kete.log.level=DEBUG
export KC_LOG_LEVEL=DEBUG,io.github.fortunen.kete:TRACE

View logs:

# Docker
docker logs -f keycloak

# Standalone
tail -f $KEYCLOAK_HOME/data/log/keycloak.log

Common Debug Scenarios¶

Extension not loading¶

Check providers/ directory has JAR
Check logs for SPI registration
Verify META-INF/services file is in JAR:
```
jar tf target/kete.jar | grep META-INF
```

Events not streaming¶

Check enabled is not set to false (defaults to true)
Check realm has listener registered:
Admin Console → Realm → Events → Event Listeners
Check destination configuration is valid
Check destination connection logs

Serialization errors¶

Add breakpoint in Serializer.serialize()
Check event structure
Verify Jackson configuration

Contributing¶

Development Workflow¶

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/kete.git
cd kete

Create a feature branch:
```
git checkout -b feature/my-new-feature
```
Make changes following code conventions
Write tests for new code
Run tests locally:
```
mvn clean test
```

Run coverage check:

mvn clean test jacoco:report
# Aim for >80% coverage

Commit with descriptive message:

git commit -m "Add SQS destination support"

Push to your fork:
```
git push origin feature/my-new-feature
```
Create Pull Request on GitHub

Pull Request Guidelines¶

One feature per PR: Keep PRs focused
Tests required: All new code must have tests
Documentation: Update docs for user-facing changes
Code style: Follow existing conventions
Clean history: Squash commits if needed
Descriptive title: "Add SQS destination" not "Update"

Commit Message Format¶

[Type] Short description

Longer description if needed explaining what and why.

Fixes #123

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - test: Test additions/changes - refactor: Code refactoring - perf: Performance improvement - chore: Build/tooling changes

Code Review Process¶

Automated checks run (tests, coverage)
Maintainer reviews code
Address feedback
Approval → Merge

Getting Help¶

Issues: Open GitHub issue for bugs/features
Discussions: Use GitHub discussions for questions
Documentation: Check existing docs first

Useful Maven Commands¶

# Build without tests
mvn clean package -DskipTests

# Run single test class
mvn test -Dtest=ProviderTest

# Run tests matching pattern
mvn test -Dtest=*Provider*

# Show dependency tree
mvn dependency:tree

# Update dependencies
mvn versions:display-dependency-updates

# Format code (if formatter configured)
mvn formatter:format

# Check for outdated plugins
mvn versions:display-plugin-updates

# Install to local Maven repo
mvn clean install

Troubleshooting¶

Build Fails¶

Problem: JAVA_HOME not set

Solution:

export JAVA_HOME=/path/to/jdk-21
# or on Windows
set JAVA_HOME=C:\Program Files\Java\jdk-21

Problem: Maven version too old

Solution: Upgrade to Maven 3.9+

mvn --version  # Check version
# Download from https://maven.apache.org/download.cgi

Tests Fail¶

Problem: Docker not running for Testcontainers

Solution: Start Docker daemon

docker ps  # Verify Docker is running

Problem: Port conflicts in tests

Solution: Stop services using ports 9092 (Kafka), 5672 (RabbitMQ)

IDE Issues¶

Problem: "Cannot resolve symbol" errors

Solution: Reimport Maven project - IntelliJ: Maven → Reload Project - Eclipse: Right-click project → Maven → Update Project - VS Code: Cmd+Shift+P → Java: Clean Language Server Workspace

Development Guide¶

Table of Contents¶

Getting Started¶

Prerequisites¶

Clone the Repository¶

IDE Setup¶

IntelliJ IDEA¶

VS Code¶

Eclipse¶

Project Structure¶

Key Files¶

Building¶

Dependency Shading (Critical)¶

Full Build¶

Skip Tests¶

Clean Build¶

Build with Coverage¶

Verify Build¶

Testing¶

Unit Tests¶

Test Naming Convention¶

Test Structure (AAA Pattern)¶

Mocking with Mockito¶

Exception Testing¶

Integration Tests¶

Coverage Reports¶

Code Conventions¶

Java Style¶

Code Example¶

Documentation¶

Extending the Extension¶

Adding a New Destination¶

Adding a New Serializer¶

Adding a New Matcher¶

Debugging¶

Local Debugging with IDE¶

Docker Debugging¶

Logging¶

Common Debug Scenarios¶

Extension not loading¶

Events not streaming¶

Serialization errors¶

Contributing¶

Development Workflow¶

Pull Request Guidelines¶

Commit Message Format¶

Code Review Process¶

Getting Help¶

Useful Maven Commands¶

Troubleshooting¶

Build Fails¶

Tests Fail¶

IDE Issues¶

Resources¶