Quarkus Support

[devhawk]

From @jonjanisch commenting on #298:

I can share a Quarkus extension I created that may be a good starting point for something official. Quarkus extensions are a bit different than Spring. Quarkus moves all reflection to compile time to avoid scanning for annotations during prod application startup.

One of the cool things about the extension is it provides automatic registration with a single annotation provided by the extension. Here's a minimal example.

@DBOSWorkflow
public class ExampleWorkflowImpl implements ExampleWorkflow {

  @Workflow(name = "example-workflow")
  public void runWorkflow() {
     // .... normal workflow code
  }
}

This is almost a complete DBOS application (interface still needed). All the boilerplate of the registration process, launching, and shutting down DBOS is removed. The only other step is setting up the config in Quarkus's properties file:

quarkus.dbos.datasource.jdbc.url=jdbc:postgresql://localhost:5432/dbos_example
quarkus.dbos.datasource.username=postgres
quarkus.dbos.datasource.password=password
quarkus.dbos.conductor-key=dbos_12345
... etc

I was about to go crazy and remove the need for the interface, but that requires bytecode manipulation which I didn't really want to attempt. At first I thought having the singleton DBOS instance would be problematic. But in practice it hasn't caused any issues.

[devhawk]

I would love to see your extension code @jonjanisch and I would be very open to creating an official transact-quarkus package, though I don't have much bandwidth for that right now.

[jonjanisch]

@devhawk - I must warn you that building a Quarkus extension is a bit ... tricky! But it's definitely interesting. So the code may be hard to grok unless you really dive into some of the quarkus extension docs. To be completely honest, most of this was built with the assistance of AI due to time constraints.

• Here's the extension: https://github.com/jonjanisch/quarkus-dbos
• Example app using it: https://github.com/jonjanisch/quarkus-dbos-starter

If you look at the commit history you can see exactly what's needed to add to a Quarkus app:

jonjanisch/quarkus-dbos-starter@5c4ac00

Note: I have not tried using it with the @Step annotations.

There's also a git branch of a vanilla quarkus / dbos implementation without the extension if that's helpful (similar to the official fault tolerant checkout spring example):

https://github.com/jonjanisch/quarkus-dbos-starter/tree/basic

Some helpful videos on building quarkus extensions:

https://www.youtube.com/watch?v=W5Lh8E-UuAI
https://www.youtube.com/watch?v=iZ501bG2ZAE

[jonjanisch]

I think for an official extension, there's an odd issue in that most users will have steps that invoke@Transactional methods using Quarkus' Hibernate extension. If the app crashes and DBOS attempts to recover workflows, those steps won't be run in a request context and an exception will be thrown. I would imagine other frameworks like Spring have the same issue. I don't know if this is something the extension can really solve.

For our application, I created a helper method runDbStep for steps which need to invoke transactional methods. Our app is also multi-tenant and in Quarkus multi-tenancy works by implementing some interface where you extract the tenant from the request (e.g. from part of the request path /api/<client>/hello, a header, oidc token, etc). Since we don't have a real request when DBOS recovers steps, this helper method sets the tenant in some TenantContext class, and our Quarkus tenant resolver checks if the tenant exists in TenantContext and if so use that.

public <E extends Exception> void runDbStep(String tenantId, ThrowingRunnable<E> stepfunc, String name) throws E {
    DBOS.runStep(runInTenantContext(tenantId, stepfunc), new StepOptions(name));
}

public <E extends Exception> ThrowingRunnable<E> runInTenantContext(String tenantId, ThrowingRunnable<E> stepfunc) {
    return () -> {
        // This is a bit ugly, but as far as i know this is the simplest way to activate Quarkus request context
        ManagedContext requestContext = Arc.container().requestContext();
        boolean activatedByUs = false;

        if (!requestContext.isActive()) {
            requestContext.activate();
            activatedByUs = true;
        }

        try {
            // Specific to our app, we store the tenant in some TenantContext class so when Quarkus
            // invokes our tenant resolver, we can obtain it from here instead of request path
            TenantContext tenantContext = Arc.container().instance(TenantContext.class).get();
            tenantContext.setTenantId(tenantId);
            stepfunc.execute();
        } finally {
            if (activatedByUs) {
                requestContext.terminate();
            }
        }
    };
}

[jonjanisch]

@devhawk I've updated the extension to use Quarkus's native datasource configuration. The native datasource will use Quarkus' agroal connection pooling library (instead of hikaricp packaged with dbos-transact-java). The only quirk I found is that the end user needs to add one line of config to disable Quarkus' built-in jakarta transactions since dbos-transact-java manages it's own transactions.

jonjanisch/quarkus-dbos-starter@0f37148#diff-54eeffbae371fcd1398d4ca5e89a1b8118208b7bb2f8ddf55c1aa2f7d98ab136R5

[devhawk]

I am at JavaOne this week so my review bandwidth is limited. But thank you!