Plumier middleware works exactly like Koa middleware, it executed in a stack-like order and has full control of the next middleware.
The different between Plumier middleware and Koa middleware is Plumier middleware is a stateless class which has a method that act like pure function. It doesn't mutate things but returns value. With this behavior Plumier middleware relatively easy to unit test in isolation.
Plumier middleware can be a function match
CustomMiddlewareFunction signature or a class that implements
CustomMiddleware interface. The signature is like below:
Middleware has one parameter
next which is an instance of
Invocation object to proceed the next middleware.
Middleware must return a promised
ActionResult, you can return result of the invocation which mean its return
result of previous middleware (its possibly the result of the action if the next middlewares doesn't modify the result).
You can also return modified version of action result or a brand new action result. You can also throw an error from
inside of middleware, the default error handler will handle it properly.
To create a plumier middleware is as easy as Koa middleware, The idea is the same but simpler. The most basic middleware that does nothing is like below:
Middleware above only execute the next middleware and pass its result into previous middleware.
More real world example is creating a error handler middleware, For example we need to log all internal error 500 into database for auditing process.
Middleware has full control of the next middleware, with this behavior we can do interception easily. There are 3 types of interception: before, after and around.
Interception occurs before the next execution proceeded. For example the authorization middleware, where the interception occur before proceeded.
Above code showing that we intercept the process before proceeding to next middleware. If the user role is not Admin then throw Unauthorized status.
Interception occurs after the next execution proceeded. For example we need to modify content of the result based on http status.
Interception occurs before and after the next execution. For example we need to log the response time of every request.
In some case you may need to set some values that will be passed to the next middleware or to the controller. Koa provide a mutable property called
state under the
Context class. You can access it anywhere under
ctx.state property on the custom extension.
Optionally, to provide the intellisense under
ctx.state.<yourProperty>, we can augment the
DefaultState type and add property you like.
Then from inside your middleware you can set the value like below
From inside controller the value can be accessed using