Skip to main content

Plugins

Genesis Gradle Settings Plugin​

The Genesis Gradle Settings plugin provides the following benefits:

  • Centralised Genesis project configuration.
  • Massive reduction in the number of lines of code in your Gradle files.
  • Consistent configuration. For example, you won't need to remember to add a dictionary dependency - the Settings plugin will add it for you.
  • Simplified development experience with the IntelliJ plugin.

This section explores the features of the Settings plugin for both structures.

How to enable?​

All modern projects should have this enabled bty default.

To manually enable, add the following to your "server" project's settings.gradle.kts file.

pluginManagement {
    val genesisVersion: String by settings

    plugins {
        id("global.genesis.settings") version genesisVersion
    }
}

plugins {
    id("global.genesis.settings")
}

Common configuration​

Once the Settings plugin has been applied, the genesis extension will be available in your project's settings.gradle.kts file.

genesis {
}

There are a few common configuration options, they are listed below:

projectType​

There are two project types:

  • APPLICATION is the default, and should be used at all other times.
  • PBC (Packaged Business Capability). Set this when the project contains reusable code and functionality that will be imported by other projects.

The differences between the two are:

  • When the project type is APPLICATION, a site-specific distribution is created in addition to the project's one.
  • When the project type is PBC, by default, the project's dictionary cache sub-modules have publishing tasks disabled. If you want to enable publishing, then disable the genesisPublicationDisabler plugin (see here for details). Projects with type APPLICATION will have publishing enabled for these modules.
genesis {
    projectType = APPLICATION
}

productName​

By default, the product name is taken from the server Gradle project's rootProject name in the settings.gradle.kts file. You can use this property to specify a custom project name.

Example usage:

genesis {
    productName = "position"
}

mainModuleName​

By default, the main module is identified by a module ending with -app

You can also set a custom name for your main module with the property mainModuleName. For example, this sets the main module name to "position-core":

genesis {
    mainModuleName = "position-core"
    productName = "position"
}

When using this property, the productName property must also be specified.

dependencies​

Here you should declare any dependencies on other Genesis products; this enables the Settings plugin to take care of where they should be added automatically.

Fo all the dependencies that you declare, the Settings plugin will:

  • import the product's dictionary, so that the tables and views are available within your project
  • capture runtime details of the product's processes, making them available to run through the Intellij plugin
  • register GPAL script definitions, to help Intellij recognize these files correctly

The syntax is similar to Gradle dependencies - but not exactly the same. Specifically, you specify the group id, product name and version: "{groupId}:{productName}:{version}"

Here is an example of adding a dependency on Auth and Genesis Notify:

genesis {
    dependencies {
        dependency("global.genesis:auth:${extra.properties["authVersion"]}")
        dependency("global.genesis:genesis-notify:${extra.properties["notifyVersion"]}")
    }
}

plugins​

Other Gradle plugins that are necessary for your project are automatically added by the Settings plugin. Below you can see the plugins that are added. These plugins can also be disabled if needed.

Plugin NamePlugin IDDescriptionEnabled by default
Kotlinorg.jetbrains.kotlin.jvmKotlin Gradle pluginYes
Genesis Buildglobal.genesis.buildCore Genesis plugin to enable build tasks, including code generationYes
Genesis Distributionglobal.genesis.distributionCreates the project's server distribution zip file. presently, this is based on the default configuration within the plugin. If you want to customize your distribution then you will need to disable this plugin and create your own configuration using the Gradle distribution plugin. In the future we will support customization from this plugin directly.Yes
Genesis Site Specific Distributionglobal.genesis.site-specific.distributionCreates the site-specific distribution zip file. Presently, this is based on the default configuration within the plugin, the same as the Genesis Distribution plugin.Yes, if project type is APPLICATION
Genesis Publication Disablerglobal.genesis.publication-disablerUsed to disable dictionary-cache sub-module publishing tasks if the project is of type PBCYes, if project type is PBC
Genesis Execglobal.genesis.execCreates Gradle tasks used by the Genesis IntelliJ plugin and Genesis Start. Applied to the main module.Yes
Genesis Deployglobal.genesis.deployCreates deployment gradle tasks (Note: not required if using Genesis IntelliJ plugin for local development)No

Here is an example of disabling the Genesis Deploy plugin:

genesis {
    plugins {
        genesisDeploy.enabled = false
    }
}

Other features​

The Settings plugin also provides some helper functions to make it simpler to add Genesis dependencies to your project.

Dependency on generated code​

To add a dependency on your project's generated code in one of your project's modules, include the following in the module's build.gradle.kts file:

dependencies {
    genesisGeneratedCode(withTestDependency = true)
}

The parameter withTestDependency is an optional parameter; it adds your generated code as a test dependency. It defaults to false.

For example, if your project is named "position", this is equivalent to:

compileOnly(project(path = ":position-dictionary-cache", configuration = "codeGen"))
testImplementation(project(path = ":position-dictionary-cache", configuration = "codeGen"))
Genesis dependency​

The Settings plugin automatically adds a Gradle platform dependency on the Genesis BOM and has some syntax sugar for adding dependencies on other Genesis modules. For example, if you want to add a dependency on genesis-eventhandler in a module’s build.gradle.kts file, include the following:

dependencies {
    dependency(genesis("eventhandler"))
}
Gradle Configuration Cache​

Genesis Gradle plugins are compatible with the Gradle configuration cache, which is enabled by default in the new project seed. This can greatly improve build times.

Exec Plugin​

The Exec plugin is key to running a Genesis application locally with either the Genesis IntelliJ plugin or Genesis Start. It is enabled by default and applied to the main module of the project.

Configuration​

The Exec plugin has a Gradle extension to customise its configuration.

Open Telemetry​

You can enable running your Genesis application processes locally with Open Telemetry. You can also provide extra JVM options which may be useful due to the many configuration options that can be provided to the Open Telemetry agent.

Example:

genesisExec {
    openTelemetry {
        enabled = true // false by default
        extraOptions = "-Dotel.traces.exporter=zipkin" // null by default
        serviceNameEnabled = true // true by default
    }
}

Genesis Build Plugin​

The Genesis Build plugin (global.genesis.build) is a core Gradle plugin that provides essential build automation and configuration for Genesis applications. It is automatically applied by the Genesis Gradle Settings plugin and handles critical build tasks including dependency management, manifest generation, code generation integration, and security checks.

Some of its key features are:

  • Automatically configuring build tasks for all project modules
  • Managing runtime dependencies for distribution packaging
  • Generating JAR manifest files with classpath and implementation details
  • Integrating code generation for dictionary cache modules
  • Enforcing security best practices through automated permission checks
  • Providing IntelliJ IDE integration tasks for local development

Automatic Module Configuration​

The plugin automatically configures all subprojects in your Genesis application:

  • copyDependencies task: Creates a copyDependencies task for application modules to collect runtime dependencies needed for distribution packaging. This task copies all runtime classpath dependencies to a central location in the build directory.

  • checkAuthPermissions task: Creates a checkAuthPermissions task to analyze the genesis application code to verify the endpoints have appropriate security configurations.

  • JAR Manifest Generation: Automatically configures JAR tasks to include manifest attributes:

    • Class-Path: Lists all runtime dependencies
    • Implementation-Vendor: Project group ID
    • Implementation-Title: Project name
    • Implementation-Version: Project version

  • Dictionary Cache Integration: Automatically applies the DictionaryCachePlugin to modules ending with -dictionary-cache, enabling code generation for system definitions, fields, DAOs, and views.

  • Product Details Creation: Applies the ProductDetailsCreatorPlugin to the distribution project to generate product metadata.

IntelliJ Integration​

To enable IntelliJ integration tasks, set the following property in your gradle.properties:

enableGenesisIntellijHelperTasks=true

When the enableGenesisIntellijHelperTasks property is set, the plugin creates deployment tasks that integrate with the Genesis IntelliJ plugin:

  • deployModuleJarsToGenesisHome: Deploys compiled JAR files to .genesis-home/{productName}/bin/
  • deployScriptsToGenesisHome: Deploys GPAL scripts from -script-config modules to .genesis-home/{productName}/scripts/
  • deployCfgToGenesisHome: Deploys configuration files from -config modules to .genesis-home/{productName}/cfg/
  • deployDaoToGenesisHome: Deploys generated DAO artifacts from dictionary cache modules to .genesis-home/{productName}/bin/

All IntelliJ helper tasks are grouped under the genesis-intellij task group for easy discovery in the IDE.

Module Filtering​

The following module types won't be applied to the copyDependencies and checkAuthPermissions tasks:

  • Modules ending with -dictionary-cache
  • Modules ending with -distribution
  • Modules ending with -deploy
  • Modules containing -generated- in their name

checkAuthPermissions​

The checkAuthPermissions task (available from version 8.14.8 onwards) automatically analyzes your Genesis application code to verify that endpoints have appropriate security configurations. It scans GPAL (Genesis Platform Abstraction Layer) DSL files, Kotlin classes, and Java classes to ensure that endpoints implement proper permission checks and authentication mechanisms.

The task is automatically registered for all application modules (excluding platform and generated code) by the GenesisBuildPlugin. It runs as part of the assemble and build tasks when enabled.

Security Model​

The task enforces a two-check security model:

  1. Permission Check: Verifies that endpoints have permission code validation

    • GPAL/KTS endpoints: Requires permissionCodes, customPermissions, or permissionCodesDisabled()
    • Class-based endpoints: Requires RightSummaryCache injection/usage

  2. Auth Check: Verifies that endpoints have authentication/authorization map configuration

    • GPAL/KTS endpoints: Requires auth(), requestAuth(), or responseAuth() blocks or authDisabled()
    • Class-based endpoints: Requires AuthCacheFactory injection/usage

An endpoint is considered secure if both checks are satisfied or explicitly disabled via annotations or opt-out properties.

Supported Endpoint Types​

GPAL/KTS Files​

The task analyzes the following GPAL file types:

  • *-dataserver.kts - Dataserver endpoints
  • *-reqrep.kts - Request-reply endpoints
  • *-eventhandler.kts - Event handler endpoints
  • *-web-handler.kts - Web handler endpoints
  • .kt files containing GPAL class definitions (e.g., GPalDataserver, GPalRequestServer, GPalEventHandler)

GPAL Analysis Features:

  1. Endpoint Detection: Identifies endpoints via DSL functions:

    • query() - Dataserver endpoints
    • requestReply() - Request-reply endpoints
    • eventHandler() - Event handler endpoints
    • endpoint() / multipartEndpoint() - Web handler endpoints

  2. Permission Code Detection: Extracts permission codes from:

    • permissionCodes("CODE1", "CODE2") - Function call syntax
    • permissionCodes = listOf("CODE1", "CODE2") - Assignment syntax
    • Global permission codes (defined at file or class level)
    • customPermissions { } blocks
    • permissionCodesDisabled() - Explicit opt-out

  3. Auth Block Detection: Identifies authentication blocks:

    • auth("MAP_NAME") { } - Standard auth block
    • requestAuth("MAP_NAME") { } - Request auth for web handlers
    • responseAuth("MAP_NAME", flow) { } - Response auth for web handlers
    • authDisabled() - Explicit opt-out

  4. Global Permissioning: Supports global permission configuration:

    • File-level permission codes (for KTS files)
    • Class-level permission codes (for .kt files with GPAL classes)
    • Global permissionCodesDisabled() and authDisabled() functions

  5. Annotation Support:

    • @AuthDisabled - Disables auth requirement (file or class level)
    • @PermissionCodesDisabled - Disables permission code requirement (file or class level)
Kotlin Class Files​

The task analyzes Kotlin classes that implement event handlers or web endpoints.

Supported Event Handler Types:

  • AsyncEventHandler<T>
  • AsyncValidatingEventHandler<T>
  • AsyncContextValidatingEventHandler<T>
  • SyncEventHandler<T, R>
  • SyncValidatingEventHandler<T, R>
  • SyncContextValidatingEventHandler<T, R>
  • AbstractEventHandler (legacy)
  • Rx3EventHandler<T, R>
  • Rx3ValidatingEventHandler<T, R>
  • Rx3ContextValidatingEventHandler<T, R>

Supported Web Endpoint Types:

  • WebEndpoint
  • BaseWebEndpoint
  • BodyLessWebEndpoint
  • AbstractAsyncEndpoint

Kotlin Analysis Features:

  1. Security Detection: Checks for:

    • RightSummaryCache injection (constructor, field, or parameter)
    • AuthCacheFactory injection (constructor, field, or parameter)

  2. Permission Code Extraction: Extracts permission codes from method calls:

    rightSummaryCache.userHasRight(userName, "PERMISSION_CODE")

  3. Auth Map Extraction: Extracts auth map names from method calls:

    authCacheFactory.newReader("MAP_NAME")

  4. Endpoint Name Resolution: Derives endpoint names from:

    • name() method override (for web endpoints)
    • messageType() method override (for event handlers)
    • Generic type parameters (for typed event handlers)
    • Constructor parameters (for AbstractEventHandler)
Java Class Files​

The task analyzes Java classes using JavaParser, with similar capabilities to Kotlin analysis.

Supported Types:

  • Same event handler interfaces as Kotlin (except async variants)
  • Same web endpoint interfaces as Kotlin (except async variants)

Java Analysis Features:

  1. Security Detection: Checks for RightSummaryCache and AuthCacheFactory in:

    • Fields
    • Constructor parameters
    • Method parameters
    • Method body usage

  2. Permission Code Extraction: Extracts from:

    rightSummaryCache.userHasRight(userName, "PERMISSION_CODE");

  3. Auth Map Extraction: Extracts from:

    authCacheFactory.newReader("MAP_NAME");

  4. Endpoint Name Resolution: Similar to Kotlin, with Java-specific parsing

Configuration​

The task behavior can be configured using Gradle properties in your gradle.properties file:

PropertyDefaultDescription
genesis.check.permission.enabledtrue (from 8.15 onwards, false otherwise)Controls whether the task runs as part of the build process
genesis.check.permission.failbuildfalseWhen true, the build will fail if any insecure endpoints are found
genesis.check.permission.systemwide.optoutfalseSystem-wide opt-out that bypasses all security checks
genesis.check.permission.auth.optoutfalseOpts out of the authentication/authorization map requirement
genesis.check.permission.extrainfofalseWhen true, the CSV report includes additional detailed columns

Example configuration:

genesis.check.permission.enabled=true
genesis.check.permission.failbuild=true
genesis.check.permission.extrainfo=false

Source Directories and Customization​

By default, the task scans: src/main/kotlin, src/main/java, src/main/resources/, src/main/resources/scripts, and src/main/genesis/scripts.

You can customize the source directories in your module's build.gradle.kts:

tasks.named<global.genesis.gradle.plugin.security.CheckAuthPermissions>("checkAuthPermissions") {
    sourceDirectories.set(
        files(
            "src/main/kotlin",
            "src/main/java",
            "src/main/genesis/scripts"
        )
    )
}

Opt-Out Mechanisms​

Security checks can be disabled via:

  • Annotations (file or class level): @AuthDisabled (import global.genesis.commons.annotation.AuthDisabled), @PermissionCodesDisabled (import global.genesis.commons.annotation.PermissionCodesDisabled)
  • DSL Functions (GPAL only): permissionCodesDisabled(), authDisabled()
  • Gradle Properties: genesis.check.permission.systemwide.optout, genesis.check.permission.auth.optout

The opt-out mechanism will mark the endpoints as "safe" rather than ignore them. Nonetheless, the endpoints will show up in the "extrainfo" report (see next section), with opt-out information included in it.

Reports​

The task generates a CSV report for each module at build/reports/genesis-security/auth-permissions.csv containing endpoint name, type, file name, class name, status (SUCCESS/FAILURE), and reason. When genesis.check.permission.extrainfo=true, additional columns include permission codes, auth maps, and security flags.

Examples​

Secure GPAL Dataserver:

query("ALL_TRADES", TRADE) {
    permissioning {
        permissionCodes("TRADE_VIEW")
        auth("COUNTERPARTY_VISIBILITY") {
            authKey { key(data.counterpartyId) }
        }
    }
}

Secure Kotlin Event Handler:

@AuthDisabled
class TradeInsertEventHandler @Inject constructor(
    private val rightSummaryCache: RightSummaryCache,
) : AsyncEventHandler<Trade, EventReply> {

    override fun messageType() = "TRADE_INSERT"

    override suspend fun process(event: Event<Trade>): EventReply {
        if (!rightSummaryCache.userHasRight(event.userName, "TRADE_INSERT")) {
            return nack("Insufficient permissions")
        }
        return ack()
    }
}

Full Opt-Out Example:

@AuthDisabled
@PermissionCodesDisabled
class InstrumentEndpoint : AbstractAsyncEndpoint("instrument") {
    // No security required
}

Execution​

Run the task manually:

./gradlew checkAuthPermissions

The task runs automatically during assemble and build when enabled. To skip it, use ./gradlew build -x checkAuthPermissions or set genesis.check.permission.enabled=false in gradle.properties.

Troubleshooting​

  • Task not running: Verify genesis.check.permission.enabled=true and that your module is not excluded
  • False positives: Use genesis.check.permission.extrainfo=true for detailed information, verify annotations are correctly applied, and ensure RightSummaryCache/AuthCacheFactory are injected (not just referenced)
  • Build failures: Review the CSV report, fix insecure endpoints or add opt-outs, or temporarily disable with genesis.check.permission.failbuild=false

The task is cacheable, and parallel-safe. For CI/CD, recommended configuration includes genesis.check.permission.enabled=true, genesis.check.permission.failbuild=true, and genesis.check.permission.extrainfo=false.

Configuration​

Automatic Application​

The Genesis Gradle Build plugin is automatically applied by the Genesis Gradle Settings plugin. You typically don't need to apply it manually.

Task Dependencies​

The plugin automatically sets up task dependencies:

  • jar task depends on copyDependencies for application modules
  • assemble and build tasks depend on checkAuthPermissions when security checks are enabled
  • checkAuthPermissions depends on compileKotlin and compileJava to ensure source files are compiled before analysis

Distribution Integration​

The plugin identifies the distribution project (a module ending with -distribution or the root project if none exists) and applies the ProductDetailsCreatorPlugin to generate product metadata required for distribution packaging.