Middlewares
In Marble.js, middlewares are streams of side-effects that can be composed and plugged-in to our request/event lifecycle to perform certain actions before reaching the designated Effect.
MiddlewareEffect :: Observable<T> -> Observable<T>
Because everything here is a stream, the plugged-in middlewares are also based on a similar Effect interface.
HttpMiddlewareEffect :: Observable<HttpRequest> -> Observable<HttpRequest>
By default, framework comes bundled with composable middlewares like: logging, request body parsing or request validator. Below you can see how simple can look a dummy HTTP request logging middleware.
logger.middleware.ts
import { HttpMiddlewareEffect, HttpRequest } from '@marblejs/http';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';
const logger$ = (req$: Observable<HttpRequest>): Observable<HttpRequest> =>
req$.pipe(
tap(req => console.log(`${req.method} ${req.url}`)),
);
// same as
const logger$: HttpMiddlewareEffect = (req$, res) =>
req$.pipe(
tap(req => console.log(`${req.method} ${req.url}`)),
);
The example above performs I/O operation for every request that comes through the stream. As you can see, the middleware, compared to the basic effect, must return the processed request at the end.
In order to use our custom middleware, we need to attach the defined middleware to the
httpListener config.import { httpListener } from '@marblejs/http';
import { logger$ } from './logger-middleware';
const middlewares = [
// 👇 our custom middleware
logger$,
];
const listener = httpListener({ middlewares, effects });
There are some cases when our custom middleware needs to be parameterized - for example, the dummy
logger$ middleware should log request URL's conditionally. To achieve this behavior we can make our middleware function curried, where the last returned function should conform toHttpMiddlewareEffect interface.import { HttpMiddlewareEffect } from '@marblejs/http';
interface LoggerOpts {
showUrl?: boolean;
}
const logger$ = (opts: LoggerOpts = {}): HttpMiddlewareEffect => req$ =>
req$.pipe(
tap(req => console.log(`${req.method} ${opts.showUrl ? req.url : ''}`)),
);
The improved logging middleware, can be composed like in the following example:
const middlewares = [
// 👇 our custom middleware
logger$({ showUrl: true }),
];
Some types of middlewares need to send an HTTP response earlier. For this case Marble.js exposes a dedicated
req.res.send method which allows to send an HTTP response using the same common interface that we use for sending a response inside API Effects. The mentioned method returns an empty Observable (Observable that immediately completes) as a result, so it can be composed easily inside a middleware pipeline.import { HttpMiddlewareEffect } from '@marblejs/http';
import { mergeMap } from 'rxjs/operators';
const middleware$: HttpMiddlewareEffect = req$ =>
req$.pipe(
mergeMap(req => req.res.send({ body: 💩, status: 304, headers: /* ... */ })),
);
If the HTTP response is sent earlier than inside the target Effect, the execution of all following middlewares and Effects will be skipped.
You can compose middlewares in four ways:
- globally (inside
httpListenerconfiguration object), - inside grouped effects (via
combineRoutesfunction), - or by composing it directly inside Effect request pipeline.
There are many scenarios where we would like to apply middlewares inside our API Effects. One of them is to authorize only specific endpoints. Going to meet the requirements, Marble.js allows us to compose them using dedicated use operator, directly inside request stream pipeline.
Let's say we have an endpoint for getting list of all users, but also we would like to make it secure, and available only for authorized users. All we need to do is to compose authorization middleware directly to the effect Observable chain.
Deprecation warning
With an introduction of version 4.0
use operator is deprecated. Apply middlewares directly to the effect Observable chain. The operator will be deleted in the next major version (v5.0).getUsers.effect.ts
import { r } from '@marblejs/http';
import { authorize$ } from './auth.middleware';
const getUsers$ = r.pipe(
r.matchPath('/'),
r.matchType('GET'),
// 👇 here...
r.use(authorize$),
r.useEffect(req$ => req$.pipe(
// 👇 or here...
authorize$,
// ...
)));
The example implementation of
authorize$ middleware can look like in the following snippet:auth.middleware.ts
import { HttpMiddlewareEffect, HttpError, HttpStatus } from '@marblejs/http';
import { of, throwError } from 'rxjs';
const authorize$: HttpMiddlewareEffect = req$ =>
req$.pipe(
mergeMap(req => !isAuthorized(req),
? throwError(() => new HttpError('Unauthorized', HttpStatus.UNAUTHORIZED)),
: of(req)),
);
There are some cases where you would like to compose a bunch of middlewares before grouped routes, e.g. to authorize only a selected group of endpoints. Instead of composing middlewares for each route separately, you can also compose them via extended second parameter of
combineRoutes() function.import { combineRoutes } from '@marblejs/http';
const api$ = combineRoutes('/api/v1', {
middlewares: [ authorize$ ],
effects: [ user$, movie$, actor$ ],
});
If your middleware should operate globally, e.g. in case of request logging, the best place is to compose it inside
httpListener. In this case the middleware will operate on each request that goes through your HTTP server.import { httpListener } from '@marblejs/http';
import { logger$ } from '@marblejs/middleware-logger';
import { bodyParser$ } from '@marblejs/middleware-body';
const middlewares = [
logger$(),
bodyParser$(),
];
const effects = [
// ...
];
export const listener = httpListener({ middlewares, effects });
The stacking order of middlewares inside
httpListener and combineRoutes matters - middlewares are run sequentially (one after another).Last modified 1yr ago