Using ScopedValue in Play Framework

[mihe-inf]

I intend to implement an audit-log for sensitive changes inside my play application, which is basically just logging but with included context information like "acting user", "remote ip", etc. I am creating a custom immutable context object that includes such values. Now the obvious way to do this with play is to instantiate the context within a Filter and add it to the request as a request attribute, and then pass the request (or just the audit-context) explicitly via method parameters to every method call.

This is not really a feasible option for me, because I am not looking to change the method signatures of basically every method inside my codebase just to add an audit-context parameter. Is it an option to use the JDK25 feature ScopedValue for this? Or does play framework's stateless nature make this too error-prone?

For example, inside a filter, after all the authn/authz checks have passed, I could do this:

final var ctx = new AuditContext.Ctx(...);
return ScopedValue.where(AuditContext.CTX, ctx).call(() -> delegate.call(request));

Then in controller methods, or other functions called within, I could access the context with:

var ctx = AuditContext.CTX.get();

I am not sure how Play Framework handles requests internally once they are flowing through the filters, will it use different threads for the same request if I do not explicitly run asynchronous code? I am aware that once I run asynchronous methods, that I have to pass on a copy of the context explicitly, the same goes for if I am sending messages to actors. In that case, I would of course include the context within the messages sent (if applicable).

Btw. I am aware that Play has moved on from using a static request context (I think it was based on ThreadLocal) and instead instructs to pass the request explicitly via method parameters. But as mentioned above, changing all method signatures in my method call stack to include a context is something I want to work around if possible.

[mihe-inf]

I just realized that this probably won't work inside a filter. But would it work if I was doing it inside the controller methods which handles the request?

public Result foo(final Http.Request request) {
    final var ctx = new AuditContext.Ctx(...);
    return ScopedValue.where(AuditContext.CTX, ctx).call(() -> {
        // some code handling the request and returning a result
        return ok();
    });
}

[mkurz]

I never looked into ScopedValue, but it looks interesting.

I am not sure how Play Framework handles requests internally once they are flowing through the filters, will it use different threads for the same request if I do not explicitly run asynchronous code?

There no guarantee that things run in the same thread. Thread switches can happen Play internally.

public Result foo(final Http.Request request) {
    final var ctx = new AuditContext.Ctx(...);
    return ScopedValue.where(AuditContext.CTX, ctx).call(() -> {
        // some code handling the request and returning a result
        return ok();
    });
}

That should be ok, but I do not understand that sense of that.

[mihe-inf]

I see, but once it reaches the controller method, I should be "safe"?

That should be ok, but I do not understand that sense of that.

A lot of my domain logic is actually inside another project which has no dependency on Play.
What it would help with is that I don't have to change all method signatures shown below.

public Result foo(final Http.Request request) {
    final var ctx = new AuditContext.Ctx(...);
    return ScopedValue.where(AuditContext.CTX, ctx).call(() -> {
        domainLogicStuff.a();
        return ok();
    });
}

public class DomainLogicStuff {

    public void a() {
        b();
    }
    
    public void b() {
        c();
    }
    
    public void c() {
        var ctx = AuditContext.CTX.get();
        // do stuff
    }

}

The ScopedValue basically does the same thing as a ThreadLocal value would, one of the differences is that it "cleans up" after itself when it finishes, so that the value doesn't leak into the next code that re-uses the same thread... In ThreadLocal this has to be done manually and there are more chances to mess up for the person writing the code. The documentation actually suggest using scoped values over ThreadLocal in most cases now.

I am not sure whether I'll actually go through with this idea, I just wanted to make sure if it even was an option. If I have to manually wrap the code in all controller methods (as opposed to a single filter or action) this is quite messy and still requires quite some work, but it would still help in not having to change most method signatures in my domain logic.

[mkurz]

I see, but once it reaches the controller method, I should be "safe"?

Yes, the code you posted, inside the action method, it's safe to use. It's just a block of code running and as long as you don't switch threads within the action method the code you posted is totally fine and "safe". Only after the action method exits Play takes over again and could internally switch threads. But when you exit the method you also already exited the scope as well. btw, you also need to take care to not switch threads in your DomainLogicStuff and then try to access the ScopedValue from such a different thread as well of course (but I guess you know that ;)

However, instead of writing that code in very action method, of course it would be comfortable to just solve this once.
I was taking a look at how Java actions methods get processed.

With Play 3.0, what you can do is:

• Option 1: Use Action composition and create an action like

@With(AuditContextStuffAction.class)
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface AuditContextStuff {
}

public class AuditContextStuffAction extends Action<AuditContextStuff> {
  public CompletionStage<Result> call(Http.Request req) {
    final var ctx = new AuditContext.Ctx(...);
    return ScopedValue.where(AuditContext.CTX, ctx).call(() -> delegate.call(req));
  }
}

and, depending on the config play.http.actionComposition.controllerAnnotationsFirst (!!!) put the annotation either on the controller itself or the action method:

@Something
@SomethingElse
@AuditContextStuffAction // Here if play.http.actionComposition.controllerAnnotationsFirst is false (default) + Needs to be last!
public class Admin extends Controller {

    @Something
    @SomethingElse
    @AuditContextStuffAction // OR (!) here if play.http.actionComposition.controllerAnnotationsFirst is true + Needs to be last!
    public Result foo(final Http.Request request) {
        domainLogicStuff.a();
        return ok();
    }
}

this way you make sure that AuditContextStuffAction directly calls the action method of the controller afterwards. Well... not directly, usually the action creator's action will run in between (by default)... So as long you haven't set play.http.actionCreator to a custom action creator, you are safe as well, as the default one just passes through the request. And if you use a custom action creator and not switch threads within it's safe as well of course.

Now... Here is the catch: That only works, if you have not set play.server.deferBodyParsing to true (false is the default anyway). Because if true, then after the annotations are processed, body parsing kicks in, which could cause a thread switch (and only then your action methods runs, maybe in a different thread).

Option 2: Talking about action creators... Instead of using annotations, with the need of putting them on either each action method or each controller class, you can solve that even more general by creating your own ActionCreator, see docs. So something like this:

public class MyActionCreator implements play.http.ActionCreator {
  @Override
  public Action createAction(Http.Request request, Method actionMethod) {
    return new Action.Simple() {
      @Override
      public CompletionStage<Result> call(Http.Request req) {
        final var ctx = new AuditContext.Ctx(...);
        return ScopedValue.where(AuditContext.CTX, ctx).call(() -> delegate.call(req));
      }
    };
  }
}

and set it via

play.http.actionCreator = "com.example.MyActionCreator"

and make sure that

play.http.actionComposition.executeActionCreatorActionFirst = false

which is the default anyway.

Now again, just before your controller's action methods run, the action creator's action will be called where you set up your scope. But again only if play.server.deferBodyParsing is set to false (!!!) - otherwise again body parsing will happen in between.

---

Now, thinking about all of that, for me it seems running body parsing in between the action creator's action method and a controller's action method is a flaw IMHO. It should be ("annotions" ->) "deferredbodyparsing" ->"actioncreator" -> "controlleraction". That way, the action creator will always run after body parsing happend, no matter if play.server.deferBodyParsing is set to true or false. Or to put it the other way: the action creator will always run directly before a contoller's action method if play.http.actionComposition.executeActionCreatorActionFirst = false, no matter if body parsing is deferred or not. Makes much more sense IMHO. So here is a PR to change that:

• Action creator's action method should always come after body parsing #13713

[mihe-inf]

Thank you for this thorough and very practical answer Matthias. I think this answers all my questions and uncertainties. Highly appreciate it.