---
title: Apply cross-cutting rules with pipeline filters
editUrl: https://github.com/Cratis/Arc.Kotlin/edit/main/Documentation/guides/pipeline-filters.mdx
description: Write command and query filters that decide for a whole feature, in Kotlin or ordinary Java, and order them deliberately.
lastUpdated: 2026-09-25T00:00:00.000Z
---

Some rules belong to an artifact. "This command needs a title" is about that command, and it lives
on that command.

Other rules belong to a whole area. "Everything in the billing feature needs the billing role" is
not really about any one command — it is about the feature — and writing it on each command in turn
means the twenty-first command is the one somebody forgets. A filter is where that kind of rule
goes: one declaration that every command or query in the pipeline passes through.

## Write a command filter

A filter sees the resolved [`CommandContext`](/arc/backend/kotlin/guides/commands/) — the command instance, its type, the
principal authentication already produced, the correlation identifier, the tenant — and returns a
result that is merged into the outcome. An unsuccessful result stops the remaining filters. It stops
the handler too when the result carries an authorization failure, an exception, or validation
feedback that is still blocking after the allowed-severity threshold is applied; warning-only
feedback is dropped by default and the handler runs:

**Java**

```java
public final class BillingCommandFilter implements BlockingCommandFilter {
    private static final String BILLING_PACKAGE = "com.example.features.billing";
    private static final String BILLING_ROLE = "billing";

    @Override
    public CommandResult<?> execute(CommandContext context) {
        if (!context.getCommandType().getName().startsWith(BILLING_PACKAGE)
            || context.getPrincipal().isInRole(BILLING_ROLE)) {
            return CommandResult.success(context.getCorrelationId());
        }
        return CommandResult.unauthorized(
            context.getCorrelationId(),
            "Role '" + BILLING_ROLE + "' is required for commands in '" + BILLING_PACKAGE + "'."
        );
    }
}
```

[View Java snippet source on GitHub](https://github.com/Cratis/Arc.Kotlin/blob/main/Documentation/client-snippets-java/guides/pipeline-filters/command-filter.md)

**Kotlin**

```kotlin
public class BillingCommandFilter : CommandFilter {
    override suspend fun execute(context: CommandContext): CommandResult<*> {
        if (!context.commandType.name.startsWith(BILLING_PACKAGE)) {
            return CommandResult.success(context.correlationId)
        }
        if (context.principal.isInRole(BILLING_ROLE)) {
            return CommandResult.success(context.correlationId)
        }
        return CommandResult.unauthorized(
            context.correlationId,
            "Role '$BILLING_ROLE' is required for commands in '$BILLING_PACKAGE'."
        )
    }

    private companion object {
        const val BILLING_PACKAGE = "com.example.features.billing"
        const val BILLING_ROLE = "billing"
    }
}
```

[View Kotlin snippet source on GitHub](https://github.com/Cratis/Arc.Kotlin/blob/main/Documentation/client-snippets/guides/pipeline-filters/command-filter.md)

Register it as a bean and it applies to every command:

**Java**

```java
@Bean
public CommandFilter billingCommandFilter() {
    return new BlockingCommandFilterAdapter(new BillingCommandFilter());
}
```

[View Java snippet source on GitHub](https://github.com/Cratis/Arc.Kotlin/blob/main/Documentation/client-snippets-java/guides/pipeline-filters/register-command-filter.md)

**Kotlin**

```kotlin
@Bean
public fun billingCommandFilter(): CommandFilter = BillingCommandFilter()
```

[View Kotlin snippet source on GitHub](https://github.com/Cratis/Arc.Kotlin/blob/main/Documentation/client-snippets/guides/pipeline-filters/register-command-filter.md)

A filter that does not apply to the command in front of it returns success and gets out of the way.
That first check is what keeps a feature's rule scoped to the feature.

This example is an ordinary filter, so it runs in `@Order` sequence with the others. Because its job
is to authorize, make it an `AuthorizationCommandFilter` (in Java, a
`BlockingAuthorizationCommandFilter` registered through `BlockingAuthorizationCommandFilterAdapter`)
when it must run before filters that cause effects. [Order them deliberately](#order-them-deliberately)
explains why.

## Write a query filter

The same shape, against `QueryContext`. The query's fully qualified name is what you match on,
because a query is a method rather than a type:

**Java**

```java
public final class BillingQueryFilter implements BlockingQueryFilter {
    private static final String BILLING_PACKAGE = "com.example.features.billing";
    private static final String BILLING_ROLE = "billing";

    @Override
    public QueryResult<?> execute(QueryContext context) {
        if (!context.getQueryName().value().startsWith(BILLING_PACKAGE)
            || context.getPrincipal().isInRole(BILLING_ROLE)) {
            return QueryResult.success(context.getCorrelationId());
        }
        return QueryResult.unauthorized(context.getCorrelationId());
    }
}
```

[View Java snippet source on GitHub](https://github.com/Cratis/Arc.Kotlin/blob/main/Documentation/client-snippets-java/guides/pipeline-filters/query-filter.md)

**Kotlin**

```kotlin
public class BillingQueryFilter : QueryFilter {
    override suspend fun execute(context: QueryContext): QueryResult<*> {
        if (!context.queryName.value.startsWith(BILLING_PACKAGE)) {
            return QueryResult.success<Any>(context.correlationId)
        }
        if (context.principal.isInRole(BILLING_ROLE)) {
            return QueryResult.success<Any>(context.correlationId)
        }
        return QueryResult.unauthorized<Any>(context.correlationId)
    }

    private companion object {
        const val BILLING_PACKAGE = "com.example.features.billing"
        const val BILLING_ROLE = "billing"
    }
}
```

[View Kotlin snippet source on GitHub](https://github.com/Cratis/Arc.Kotlin/blob/main/Documentation/client-snippets/guides/pipeline-filters/query-filter.md)

A query filter runs for observable queries too, at subscription time — so a rule written once covers
both the one-shot `GET` and the live subscription.

## In ordinary Java

Java implementations never implement a suspending method. Pick the adapter that matches how your
code is already written:

| Your code | Implement | Register with |
| --- | --- | --- |
| Synchronous | `BlockingCommandFilter` / `BlockingQueryFilter` | `BlockingCommandFilterAdapter` / `BlockingQueryFilterAdapter` |
| `CompletionStage` | `AsyncCommandFilter` / `AsyncQueryFilter` | `AsyncCommandFilterAdapter` / `AsyncQueryFilterAdapter` |

A filter whose job is to authorize has its own variant of each interface. Its adapter keeps it in
the authorization group that runs first:

- `BlockingAuthorizationCommandFilter`, registered with `BlockingAuthorizationCommandFilterAdapter`
- `BlockingAuthorizationQueryFilter`, registered with `BlockingAuthorizationQueryFilterAdapter`
- `AsyncAuthorizationCommandFilter`, registered with `AsyncAuthorizationCommandFilterAdapter`
- `AsyncAuthorizationQueryFilter`, registered with `AsyncAuthorizationQueryFilterAdapter`

A blocking filter occupies a request thread for as long as it runs. Keep it to decisions it can make
from the context it already has; if it needs to call something remote, use the `CompletionStage`
form instead.

## Order them deliberately

Filters are collected in Spring `@Order` sequence, and that order is the complete rule — there is no
hidden precedence:

**Java**

```java
@Bean
@Order(10)
public CommandFilter auditFilter() {
    return new BlockingCommandFilterAdapter(new AuditCommandFilter());
}

@Bean
@Order(20)
public CommandFilter billingFilter() {
    return new BlockingCommandFilterAdapter(new BillingCommandFilter());
}
```

[View Java snippet source on GitHub](https://github.com/Cratis/Arc.Kotlin/blob/main/Documentation/client-snippets-java/guides/pipeline-filters/order.md)

**Kotlin**

```kotlin
@Bean
@Order(10)
public fun auditFilter(): CommandFilter = AuditCommandFilter()

@Bean
@Order(20)
public fun billingFilter(): CommandFilter = BillingCommandFilter()
```

[View Kotlin snippet source on GitHub](https://github.com/Cratis/Arc.Kotlin/blob/main/Documentation/client-snippets/guides/pipeline-filters/order.md)

Authorization filters are the one exception: a filter implementing `AuthorizationCommandFilter` or
`AuthorizationQueryFilter` runs before the rest regardless of its order, so a rule that denies access
is never reached after a filter that has already caused an effect. Implement that interface when your
filter's job is to authorize, and the ordinary one when it is not.

## When not to reach for a filter

A filter is the wrong tool when the rule is about one artifact. `@Authorize` and `@Roles` on the
command or the query say the same thing closer to the code they govern, are visible in the generated
client and the OpenAPI document, and do not require a reader to go looking for a bean that might
apply. See [authentication and authorization](/arc/backend/kotlin/guides/security/).

Use a filter when the rule genuinely spans artifacts, and prefer matching on something structural —
a package prefix — over a list of names somebody has to maintain.

## See it running

The [samples](https://github.com/Cratis/Arc.Kotlin/blob/main/Samples/README.md) include a Cross-Cutting Authorization page backed by exactly
this pattern, in
[Kotlin](https://github.com/Cratis/Arc.Kotlin/blob/main/Samples/Kotlin/SpringBoot/src/main/kotlin/io/cratis/arc/samples/kotlin/springboot/features/crosscuttingauthorization/CrossCuttingAuthorizationFilters.kt)
and in
[Java](https://github.com/Cratis/Arc.Kotlin/blob/main/Samples/Java/SpringBoot/src/main/java/io/cratis/arc/samples/javaspringboot/features/crosscuttingauthorization/CrossCuttingAuthorizationFilters.java).
Run `./Samples/run.sh`, open the page, and add or remove the role in the toolbar to watch both the
command and the query change their answer.
