Documentation Index

Fetch the complete documentation index at: https://platform.docs.zenoo.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Plugin System in Zenoo Hub

​

Overview

​

Benefits

• Extensibility: Add new features and integrations without modifying the Hub core.
• Modularity: Develop, test, and deploy plugins independently.
• Maintainability: Isolate customer-specific or experimental logic from the main platform.
• Rapid Innovation: Prototype and roll out new capabilities quickly.

​

Architecture

​

Types of Plugins

• Custom Connectors: Integrate with external APIs, databases, or services.
• Transport Customizers: Enhance HTTP transports with custom authentication, filters, circuit breakers, or advanced features.
• Hub Components: Add new orchestration steps, validators, or business logic.

​

Development Workflow

1. Create a Plugin Project: Use the provided SDK or follow the Plugin Connector Development guide.
2. Implement Plugin Logic: Write your custom connector or component, specifying dependencies as needed.
3. Package the Plugin: Build a JAR (or other supported format) containing your code and resources.
4. Test Locally: Use the Hub’s testing tools or a local instance to validate your plugin.

​

Example: Adding a New Hub Component as a Plugin

​

1. Implement the Plugin Component

package com.zenoo.plugin

import com.zenoo.hub.plugin.sdk.ComponentBuilder
import com.zenoo.hub.plugin.sdk.ComponentFactory
import org.osgi.service.component.annotations.Component

@Component
class PluginComponent implements ComponentFactory {
    @Override
    ComponentBuilder define() {
        return ComponentBuilder.component {
            dependencies {
                connector 'plugin'
            }
            exposed('test') { payload ->
                exchange('plugin') {
                    connector 'plugin'
                    config payload
                }
            }
        }
    }
}

• The @Component annotation registers this class as an OSGi component.
• The define() method returns a ComponentBuilder using a Groovy DSL to declare dependencies and exposed operations.
• The exposed('test') block defines an entry point named test for this component.

​

2. Package the Plugin

• Ensure your build includes the necessary dependencies and OSGi metadata.
• Build your project as a JAR file (a fat/uber JAR if needed).

​

3. Deploy the Plugin

• Place the JAR in the Hub’s plugin directory or deploy it using the Hub’s deployment mechanism.
• The Hub will detect and load your new component, making it available in workflow definitions as test (or the name you expose).

​

Example: Creating a Transport Customizer Plugin

​

Use Cases for Transport Customizers

• Advanced Authentication: OAuth2 flows, mTLS, API key rotation
• Resilience Patterns: Circuit breakers, retry logic, fallback mechanisms
• Custom Headers: Dynamic headers, correlation IDs, API versioning
• Monitoring: Request/response logging, timing metrics, tracing
• Content Transformation: Custom codecs, request/response interceptors

​

1. Create a Typed Configuration Class

package com.zenoo.plugin;

import com.zenoo.hub.plugin.sdk.PluginConfig;
import jakarta.validation.constraints.NotNull;
import lombok.Data;

@Data
public class HttpTransportConfig implements PluginConfig {

    @NotNull(message = "Custom header name is required")
    private String customHeaderName = "X-Custom-Header";

    @NotNull(message = "Custom header value is required")
    private String customHeaderValue = "default-value";

    private Boolean enableDetailedLogging = false;
}

• Use @Data from Lombok for automatic getters/setters
• Add JSR-303 validation annotations (@NotNull, @Min, @Max, etc.)
• Provide sensible defaults for optional fields
• No need for Jackson annotations (Hub handles mapping automatically)

​

2. Implement the Transport Customizer

package com.zenoo.plugin;

import com.zenoo.hub.plugin.sdk.TransportCustomizer;
import com.zenoo.hub.plugin.sdk.PluginConfig;
import org.osgi.service.component.annotations.Component;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.reactive.function.client.ClientRequest;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

import java.util.UUID;

@Component
public class CustomHttpTransportCustomizer implements TransportCustomizer {

    private static final Logger log = LoggerFactory.getLogger(CustomHttpTransportCustomizer.class);

    @Override
    public String name() {
        return "custom-http";
    }

    @Override
    public Class<? extends PluginConfig> configType() {
        return HttpTransportConfig.class;
    }

    @Override
    public WebClient customize(WebClient baseClient, PluginConfig config) {
        if (config == null) {
            log.debug("No configuration provided, returning base client unchanged");
            return baseClient;
        }

        HttpTransportConfig httpConfig = (HttpTransportConfig) config;
        log.info("Customizing HTTP transport with config: {}", httpConfig);

        // Use mutate() to ENHANCE base client (preserves DSL baseUrl & auth)
        WebClient.Builder builder = baseClient.mutate();

        // Add custom headers filter
        ExchangeFilterFunction customHeadersFilter = ExchangeFilterFunction.ofRequestProcessor(request -> {
            ClientRequest modifiedRequest = ClientRequest.from(request)
                    .header(httpConfig.getCustomHeaderName(), httpConfig.getCustomHeaderValue())
                    .header("X-API-Version", "1.0")
                    .header("X-Correlation-ID", UUID.randomUUID().toString())
                    .build();
            return Mono.just(modifiedRequest);
        });
        builder.filter(customHeadersFilter);

        // Add timing filter
        ExchangeFilterFunction timingFilter = (request, next) -> {
            long startTime = System.currentTimeMillis();
            return next.exchange(request).doOnSuccess(response -> {
                long duration = System.currentTimeMillis() - startTime;
                log.info("Request to {} took {}ms", request.url(), duration);
            });
        };
        builder.filter(timingFilter);

        // Conditional logging based on config
        if (Boolean.TRUE.equals(httpConfig.getEnableDetailedLogging())) {
            builder.filter(ExchangeFilterFunction.ofRequestProcessor(request -> {
                log.debug("Outgoing request: {} {}", request.method(), request.url());
                return Mono.just(request);
            }));
        }

        return builder.build();
    }
}

• name(): Returns the unique identifier for this customizer within the plugin
• configType(): Returns the configuration class type for automatic mapping and validation
• customize(): Receives the pre-configured baseClient (with DSL baseUrl & auth) and your typed config
• Always use baseClient.mutate() to preserve DSL settings while adding enhancements
• Return the unmodified baseClient if no customization is needed

​

3. Using Transport Customizers in DSL

// Define DSL transport with baseUrl and authentication
transport('custom-http') {
    baseUrl 'https://api.example.com'
    bearer {
        clientId 'my-client'
        clientSecret 'secret'
        tokenUri 'https://auth.example.com/token'
    }
}

// Component configuration for the customizer
config {
    customHeaderName 'X-API-Key'
    customHeaderValue config('api.key')
    enableDetailedLogging true
}

// Use in workflow - gets DSL baseUrl + auth + custom enhancements
workflow('my-workflow') {
    exchange('api-call') {
        http {
            transport 'custom-http'  // References customizer by name
            url '/api/endpoint'
            method 'POST'
            body([data: 'value'])
        }
    }
}

1. Hub creates base WebClient from DSL transport (baseUrl + bearer auth)
2. Hub looks up customizer by name 'custom-http'
3. Hub maps component config to HttpTransportConfig and validates it
4. Hub calls customizer.customize(baseClient, typedConfig)
5. Your customizer adds filters using mutate()
6. Enhanced WebClient is used for HTTP requests

​

4. Build Configuration for OSGi

plugins {
    id 'java-library'
    id 'biz.aQute.bnd.builder' version '7.1.0'
}

dependencies {
    implementation project(':component-sdk')
    annotationProcessor "org.projectlombok:lombok:${lombokVersion}"
}

jar {
    manifest {
        attributes(
            'Bundle-SymbolicName': 'my-plugin',
            'Bundle-Version': '1.0.0',
            'Service-Component': '*',
            'Import-Package': '!groovy.*,!org.springframework.*,!reactor.*,*'
        )
    }
}

• Exclude Spring and Reactor from Import-Package (they’re loaded via boot delegation)
• 'Service-Component': '*' enables OSGi Declarative Services
• The bnd.builder plugin generates proper OSGi metadata

​

5. Karaf Configuration

org.osgi.framework.bootdelegation=org.codehaus.groovy.*,groovy.*,org.springframework.*,reactor.*

​

Deployment Process

• Deploy to Hub: Place the plugin artifact in the designated plugins directory or use the Hub’s deployment API.
• Activation: The Hub detects new plugins and loads them at runtime, making new components available for use in workflows.
• Hot Reload (if supported): Some environments allow plugins to be updated without restarting the Hub.

​

Versioning and Isolation

• Each plugin is versioned independently, allowing safe upgrades and rollbacks.
• Plugins run in isolated classloaders to avoid dependency conflicts.

​

Best Practices

​

General Plugin Development

• Keep plugins focused and single-purpose.
• Document plugin APIs and configuration options.
• Use semantic versioning for plugin releases.
• Test plugins thoroughly before deployment.
• Monitor plugin performance and errors using Hub’s observability tools.

​

Transport Customizer Best Practices

• Always use baseClient.mutate() to preserve DSL configuration (baseUrl, auth)
• Return unmodified baseClient when config is null or no customization needed
• Use typed configuration with PluginConfig and JSR-303 validation for type safety
• Avoid overriding DSL settings unless explicitly required by your use case
• Be cautious with logging - avoid exposing sensitive data (credentials, tokens, PII)
• Implement proper error handling with meaningful exceptions
• Consider thread safety - the returned WebClient is cached and used concurrently
• Add filters for cross-cutting concerns - logging, timing, custom headers
• Test with various DSL transport configurations to ensure decorator pattern works correctly
• Document which DSL settings your customizer depends on or modifies

​

Related Guides

• Plugin Connector Development
• Custom Connector Development