Become a member!

DelphiMVCFramework 3.5.0-silicon : des middleware aux filtres, qu'arrive-t-il à ton serveur ?

🌐
Cet article est aussi disponible dans d'autres langues :
🇮🇹 Italiano  •  🇬🇧 English  •  🇪🇸 Español  •  🇩🇪 Deutsch  •  🇧🇷 Português

DelphiMVCFramework, le framework open source REST et web pour Delphi

Un middleware classique de DelphiMVCFramework a quatre méthodes. Un filtre HTTP a une seule procédure. Pourquoi ai-je changé un mécanisme qui fonctionnait depuis des années, où vont les quatre hooks, dans quel ordre enregistres-tu les filtres, et que devient le serveur que tu as déjà en production ?

Pendant des années, dans DelphiMVCFramework, on a accroché du code au cycle d’une requête avec les middleware, via AddMiddleware. Les filtres HTTP sont arrivés avec la Minimal API de la 3.5, celle du post sur la RC6. Désormais, les filtres prennent la place des middleware là où il en existe un équivalent : dix-sept middleware sont marqués deprecated, chacun avec son filtre. Ce sera dans la RC9 de la 3.5.0-silicon.

✅ Ce n'est pas un breaking change. Les serveurs actuels continuent de fonctionner de la même façon, sans modification et sans problème.

Dans la 3.5.0-silicon, les filtres sont une fonctionnalité supplémentaire : les middleware restent où ils sont, et le compilateur affiche un avertissement pour chaque middleware marqué deprecated. Il y aura un breaking change avec la 4.0, où les middleware seront supprimés complètement.

DelphiMVCFramework est le framework le plus populaire de son genre sur GitHub pour Delphi, avec plus de 50 contributeurs, et il est utilisé dans des environnements critiques : hôpitaux, banques, usines, jeux vidéo, ERP avec des centaines d'utilisateurs. C'est pour cela que j'ai choisi une transition douce, sans traumatisme.

Dans cet article, je parle des deux types de filtre, ceux qui s’exécutent avant le routing et ceux qui s’exécutent après, et des bundles, qui les enregistrent ensemble.

Dans cet article


Deux responsabilités dans une classe

Jusqu’ici, un middleware faisait deux choses. Avec OnBeforeRouting et OnAfterRouting, il influençait le routing : il pouvait répondre avant que le routeur regarde la requête, pour servir un fichier statique, faire une redirection ou répondre à un preflight CORS, et, à la fin de la requête, observer ou modifier la réponse, comme le font ETag et analytics. Avec OnBeforeControllerAction et OnAfterControllerAction, il contrôlait la manière dont les actions étaient exécutées. Quatre méthodes dans une seule classe, pour deux tâches différentes.

Ceux qui me connaissent, ou qui ont suivi l’un de mes cours, savent l’importance que j’accorde aux principes SOLID. Trouver une classe à deux tâches dans mon projet open source le plus populaire me dérangeait vraiment. Chaque fois que je touchais à un middleware, je le voyais : soit on utilisait la paire de méthodes du routing (OnBeforeRouting et OnAfterRouting) en laissant les deux autres vides, soit on implémentait la paire de l’endpoint (OnBeforeControllerAction et OnAfterControllerAction), qui connaît déjà controller et action parce qu’elle s’exécute après le routing. Il était évident que ce composant devait être refactorisé. Le moment est venu.

La violation est celle du principe de responsabilité unique (SRP). Je l’ai résolue avec un mécanisme qui existe dans beaucoup de frameworks : une fonction qui reçoit la requête et un next à appeler pour passer la main à ce qui vient après. Ce mécanisme est utilisé par Express (next()) et Koa (await next()) en Node.js, ASP.NET Core (await next(context)) en C#, Laravel ($next($request)) en PHP, Starlette et FastAPI (call_next) en Python, Gin (c.Next()) en Go et axum (next.run(request)) en Rust.

C’est la Chain of Responsibility, dans la variante appelée Intercepting Filter : chaque maillon peut agir avant, passer la main avec next et agir après, ou s’arrêter. Dans DelphiMVCFramework, ce next s’appelle ANext. La première responsabilité passe aux filtres HTTP, la seconde aux filtres d’endpoint.


Comment fonctionne un filtre HTTP

Un filtre HTTP est cette procédure :

Signature d’un filtre HTTP : une procédure avec AContext de type TWebContext et ANext de type TMVCHTTPFilterNext

Copier le code
procedure(const AContext: TWebContext; const ANext: TMVCHTTPFilterNext)

Il enveloppe toute la requête : les middleware classiques, le routing et l’action. Ce que tu écris avant ANext() s’exécute avant tout, ce que tu écris après s’exécute quand la réponse est complète, c’est-à-dire après l’action. Pour arrêter la requête, tu n’appelles pas ANext(), et aucune action n’est exécutée.

Il s’appelle HTTP parce qu’il travaille au niveau du protocole : il voit la méthode, les en-têtes et le body de la requête et de la réponse. Il fonctionne aussi avec HTTPS, parce que le chiffrement TLS se trouve plus bas et que le filtre reçoit la requête déjà déchiffrée.

Middleware classiqueFiltre HTTP
InterfaceIMVCMiddleware, quatre méthodesune procédure avec AContext et ANext
S’enregistre avecAEngine.AddMiddleware(...)AEngine.Use(...)
Quand il s’exécuteaux quatre points du cycle, dans l’ordre d’enregistrementautour de toute la requête : middleware classiques, routing et action
Avant et aprèsdeux méthodes séparéesmême procédure : avant et après ANext()
Pour arrêter la requêteHandled := Truetu n’appelles pas ANext()
Controllerouioui

Use est une méthode de TMVCEngine et renvoie TMVCEngine, tu peux donc enchaîner les appels. C’est la même méthode pour les filtres HTTP, les filtres d’endpoint et les bundles, et c’est le type de l’argument qui choisit la surcharge. C’est pour cela qu’une fonction de filtre sans paramètres passée à Use demande les parenthèses, ETagHTTPFilter() : sans elles, le compilateur ne sait pas quelle surcharge utiliser (E2250). Les filtres prêts à l’emploi se trouvent dans MVCFramework.Filters, et le nom indique le type : il se termine par HTTPFilter, par EndpointFilter ou, pour un bundle, par Bundle.

Le filtre HTTP fonctionne de la même façon avec les controllers et avec la Minimal API, et c’est pour cela que le wizard peut utiliser la même chaîne dans les deux cas. Les middleware et les filtres HTTP sont traités au chapitre 14 du guide officiel, deuxième édition, les filtres d’endpoint et la Minimal API au chapitre 29.


Où vont les quatre hooks ?

  • OnBeforeRouting devient le code avant ANext().
  • OnAfterRouting devient le code après ANext(). Le nom est trompeur : il se déclenche à la toute fin, pas juste après le routing. Si l’action lève une exception, l’engine la gère à l’intérieur de ANext() et répond 500, et le code après ANext() s’exécute quand même, comme OnAfterRouting. Un try..finally autour de ANext() est utile pour les exceptions qui viennent d’un filtre HTTP plus intérieur.
  • OnBeforeControllerAction et OnAfterControllerAction n’ont pas d’équivalent dans un filtre HTTP. Ils reçoivent le nom du controller et celui de l’action, qu’on ne connaît qu’après le routing, alors que le filtre HTTP enveloppe toute la requête sans les connaître. Le filtre d’endpoint (EndpointFilter), qui s’exécute après le routing, les connaît : c’est la seconde responsabilité, et j’en parle plus loin.

Un filtre écrit à la main

Pas besoin de classe pour écrire un filtre : tu passes à Use une méthode anonyme avec la signature que tu viens de voir. Celui-ci ajoute deux en-têtes de sécurité à chaque réponse :

Filtre HTTP écrit à la main qui définit les en-têtes X-Content-Type-Options et X-Frame-Options puis appelle ANext

Copier le code
AEngine.Use(
  procedure(const AContext: TWebContext; const ANext: TMVCHTTPFilterNext)
  begin
    AContext.Response.SetCustomHeader('X-Content-Type-Options', 'nosniff');
    AContext.Response.SetCustomHeader('X-Frame-Options', 'DENY');
    ANext();
  end);

Tu définis les en-têtes avant ANext(), pour qu’une action qui veut une autre valeur puisse l’écraser. Le filtre prêt à l’emploi SecurityHeadersHTTPFilter() met X-XSS-Protection: 0 et X-Content-Type-Options: nosniff. Celui-ci est écrit à la main pour montrer la forme, et il ajoute X-Frame-Options.

Un filtre peut aussi arrêter la requête. Celui-ci répond 400 aux POST, PUT et PATCH dont le body est vide ou ne contient que des espaces, avant que le routing la regarde :

Filtre HTTP qui répond 400 aux POST, PUT et PATCH dont le body est vide ou ne contient que des espaces et qui n’appelle ANext que dans la branche else

Copier le code
AEngine.Use(
  procedure(const AContext: TWebContext; const ANext: TMVCHTTPFilterNext)
  begin
    if (AContext.Request.HTTPMethod in [httpPOST, httpPUT, httpPATCH]) and
      AContext.Request.Body.Trim.IsEmpty then
    begin
      AContext.Response.StatusCode := HTTP_STATUS.BadRequest;
      AContext.Response.ContentType := TMVCMediaType.APPLICATION_JSON;
      AContext.Response.Content := '{"message":"The body must not be blank"}';
    end
    else
      ANext();
  end);

ANext() est dans la branche else : quand le filtre rejette la requête, ANext() n’est pas appelé et aucun controller ne la voit.


Les dix-sept middleware dépréciés

Dix-sept middleware sont marqués deprecated : quatorze classes TMVC...Middleware et trois fonctions Use...SessionMiddleware, qui créent les middleware de session. Chacun a son filtre dans MVCFramework.Filters :

Middleware dépréciéFiltreComment l’enregistrer
TMVCRedirectMiddlewareRedirectHTTPFilterUse(RedirectHTTPFilter(['/'], '/web'))
TMVCStaticFilesMiddlewareStaticFilesHTTPFilterUse(StaticFilesHTTPFilter('/static', lWwwPath))
TMVCAnalyticsMiddlewareAnalyticsHTTPFilterUse(AnalyticsHTTPFilter())
TMVCTraceMiddlewareTraceHTTPFilterUse(TraceHTTPFilter())
TMVCCompressionMiddlewareCompressionHTTPFilterUse(CompressionHTTPFilter(1024))
TMVCETagMiddlewareETagHTTPFilterUse(ETagHTTPFilter())
TMVCCORSMiddlewareCORSHTTPFilterUse(CORSHTTPFilter('*'))
TMVCSecurityHeadersMiddlewareSecurityHeadersHTTPFilterUse(SecurityHeadersHTTPFilter())
TMVCShutdownMiddlewareShutdownHTTPFilterUse(ShutdownHTTPFilter('apikey', 'a-strong-secret'))
TMVCRangeMediaMiddlewareRangeMediaHTTPFilterUse(RangeMediaHTTPFilter('/static/media', 'static/media'))
TMVCSwaggerMiddlewareSwaggerHTTPFilterUse(SwaggerHTTPFilter(AEngine, lSwaggerInfo, '/openapi.json'))
TMVCOpenAPI3MiddlewareOpenAPIHTTPFilterUse(OpenAPIHTTPFilter(AEngine, lOpenAPIInfo, '/openapi.json'))
TMVCRateLimitMiddlewareRateLimitHTTPFilterUse(RateLimitHTTPFilter(lRateLimitOptions))
TMVCActiveRecordMiddlewareActiveRecordHTTPFilterUse(ActiveRecordHTTPFilter('conn_def_name', 'FDConnectionDefs.ini'))
UseMemorySessionMiddlewareMemorySessionHTTPFilterUse(MemorySessionHTTPFilter(10, [scfHttpOnly, scfSecure]))
UseFileSessionMiddlewareFileSessionHTTPFilterUse(FileSessionHTTPFilter(10, 'sessions', [scfHttpOnly, scfSecure]))
UseDatabaseSessionMiddlewareDatabaseSessionHTTPFilterUse(DatabaseSessionHTTPFilter(10, [scfHttpOnly, scfSecure])), après ActiveRecordHTTPFilter

ActiveRecordHTTPFilter et DatabaseSessionHTTPFilter ne se trouvent pas dans MVCFramework.Filters mais dans MVCFramework.Filters.ActiveRecord, SwaggerHTTPFilter dans MVCFramework.Filters.Swagger et OpenAPIHTTPFilter dans MVCFramework.Filters.OpenAPI. La couche de base ne dépend ainsi ni de FireDAC, ni de SwagDoc, ni de l’émetteur OpenAPI. Si tu utilises ces filtres, ajoute l’unit à la uses.

WaitForShutdownOrConsoleReturn, qui dans TMVCShutdownMiddleware était une méthode de classe, est maintenant une procédure de MVCFramework.Filters. StaticFilesHTTPFilter a aussi une surcharge qui prend un TMVCStaticFilesOptions, avec les options du middleware classique : charset, fallback pour les single page applications, personnalisation des types MIME, règles par requête.

Les cinq derniers sont de nouveaux filtres, que les controllers peuvent aussi utiliser de cette façon :

  • Les filtres de session mettent la factory de session sur chaque requête, et Context.Session s’utilise comme toujours. DatabaseSessionHTTPFilter doit être enregistré après ActiveRecordHTTPFilter.
  • ActiveRecordHTTPFilter prend la connexion avant le dispatch et la libère quand ANext() revient. Les connexions supplémentaires s’appliquent à chaque instance du filtre : le middleware ne les activait que pour la première du processus.
  • RateLimitHTTPFilter avec TMVCRateLimitOptions a les mêmes options et la même réponse que le middleware : clé par IP, utilisateur, API key ou personnalisée, préfixes de chemin exclus, préfixe des en-têtes X-RateLimit-*, un callback quand une requête est rejetée. La réponse est 429 avec Retry-After et un body JSON. La forme simple, RateLimitHTTPFilter(10, 60), existe toujours.

Si ton code utilise encore l’un de ces middleware, le compilateur te dit ceci :

[dcc32 Warning] W1000 Symbol 'TMVCStaticFilesMiddleware' is deprecated: 'Use the StaticFiles HTTP filter (MVCFramework.Filters): AEngine.Use(StaticFilesHTTPFilter(...))'

C’est un avertissement, pas une erreur. Le code continue de compiler et de fonctionner.


Ce que génère le wizard

Par conséquent, le wizard des nouveaux projets, celui du post sur la RC7, génère les filtres à la place de ces middleware. Pour un projet à controllers avec fichiers statiques, CORS, ETag, compression, trace, rate limit, ActiveRecord et sessions, EngineConfigU contient une seule chaîne :

Chaîne de filtres générée par le wizard dans EngineConfigU : RedirectHTTPFilter, FileServerBundle, TraceHTTPFilter, CORSHTTPFilter, ETagHTTPFilter, CompressionHTTPFilter, RateLimitHTTPFilter, ActiveRecordHTTPFilter et MemorySessionHTTPFilter, chacun enregistré avec AEngine.Use

Copier le code
  // HTTPFilter chain (engine-wide). Order matters: first = outermost. The filters wrap the whole
  // request: the classic middleware, the routing and the action.
  AEngine.Use(RedirectHTTPFilter(['/'], '/web'));
  AEngine.Use(FileServerBundle('/static', lWwwPath));
  AEngine.Use(TraceHTTPFilter());
  AEngine.Use(CORSHTTPFilter('*'));
  AEngine.Use(ETagHTTPFilter());
  AEngine.Use(CompressionHTTPFilter(1024));
  AEngine.Use(RateLimitHTTPFilter(lRateLimitOptions));
  AEngine.Use(ActiveRecordHTTPFilter(
    dotEnv.Env('firedac.connection_definition_name', 'activerecorddb'),
    dotEnv.Env('firedac.connection_definitions_filename', TPath.Combine(AppPath, 'FDConnectionDefs.ini'))
  ));
  AEngine.Use(MemorySessionHTTPFilter(10, SessionCookieFlags(dotEnv.Env('SESSION_COOKIE_SECURE', True))));

Le bloc est un exemple : les noms de la connexion dépendent du projet généré, et lRateLimitOptions est préparé un peu plus haut avec TMVCRateLimitOptions.Default.

Le premier enregistré est le plus extérieur. L’ordre qu’utilise le wizard est RedirectHTTPFilter, FileServerBundle, AnalyticsHTTPFilter, TraceHTTPFilter, CORSHTTPFilter, ETagHTTPFilter, CompressionHTTPFilter, RateLimitHTTPFilter, la documentation de l’API, ActiveRecordHTTPFilter et les filtres de session. Les sessions et la connexion à la base de données sont au point le plus intérieur, de sorte qu’une requête rejetée avec 429 ou servie comme fichier statique n’ouvre pas de connexion.

Pour les fichiers statiques, le wizard utilise FileServerBundle à la place de StaticFilesHTTPFilter. Il sert les fichiers de la même façon et répond en plus aux requêtes qui ont l’en-tête Range par 206 Partial Content, comme RangeMediaHTTPFilter. Un bundle est un ensemble de filtres qu’un seul Use enregistre dans le bon ordre ; celui-ci n’a que la partie HTTP.

ETagHTTPFilter se place avant CompressionHTTPFilter parce qu’il calcule le hash après le retour de ANext(). Si ETagHTTPFilter est plus extérieur, la compression a déjà réécrit le body, et l’ETag correspond aux octets que le client reçoit.

Par rapport à AddMiddleware, l’ordre d’enregistrement ne compte pas : les filtres enveloppent de toute façon les middleware classiques, même ceux qui répondent seuls, comme les fichiers statiques ou la redirection.

Pour OpenAPI et Swagger, le wizard utilise Use(SwaggerHTTPFilter(...)) pour l’endpoint du document et Use(StaticFilesHTTPFilter(lSwaggerUIOptions)) pour la Swagger UI sous /swagger. Il en va de même pour les projets WebBroker et pour les projets Minimal API, qui utilisaient déjà la chaîne.

Dans la uses, le wizard n’écrit plus MVCFramework.Middleware.Redirect, .StaticFiles, .Analytics, .Trace, .CORS, .ETag, .Compression, .Swagger, .RateLimit, .Session et .ActiveRecord. Il ajoute MVCFramework.Filters et, quand il le faut, MVCFramework.Filters.ActiveRecord, MVCFramework.Filters.Swagger et MVCFramework.Filters.OpenAPI, plus MVCFramework.MinimalAPI dans les projets Minimal API.

Le wizard installé dans l’IDE génère à partir des templates qu’il a dans le package. Pour voir la nouvelle chaîne, il faut le package de la RC9.


Si tu migres un projet

Avec la 4.0, les middleware n’existeront plus ; pour les middleware qui ont déjà un filtre, le passage doit donc se faire avant la mise à jour. Pour les trois plus courants, c’est ceci (dans la uses, ajoute MVCFramework.Filters). StaticFilesHTTPFilter sous cette forme n’est pas identique au middleware : le fallback pour les single page applications est désactivé, j’en parle plus bas :

Avant et après : AddMiddleware avec TMVCRedirectMiddleware, TMVCStaticFilesMiddleware et TMVCCORSMiddleware devient Use avec RedirectHTTPFilter, StaticFilesHTTPFilter et CORSHTTPFilter

Copier le code
// before
AEngine.AddMiddleware(TMVCRedirectMiddleware.Create(['/'], '/web'));
AEngine.AddMiddleware(TMVCStaticFilesMiddleware.Create('/static', lWwwPath));
AEngine.AddMiddleware(TMVCCORSMiddleware.Create);

// after
AEngine.Use(RedirectHTTPFilter(['/'], '/web'));
AEngine.Use(StaticFilesHTTPFilter('/static', lWwwPath));
AEngine.Use(CORSHTTPFilter('*'));

Les valeurs par défaut de certains filtres diffèrent de celles du middleware. J’ai comparé le code source des deux, filtre par filtre, pour ceux qui suivent.

CORS

TMVCCORSMiddlewareCORSHTTPFilter
Credentialsactivésdésactivés
En-têtes autorisésContent-Type, Accept, jwtusername, jwtpassword, authentication, authorizationContent-Type,Authorization
MéthodesPOST,GET,OPTIONS,PUT,DELETE,PATCHGET,POST,PUT,DELETE,PATCH,OPTIONS
Max-age60 secondes1728000 secondes

Si un client dépend des anciennes valeurs, tu les passes comme paramètres :

CORSHTTPFilter avec les paramètres qui reproduisent les valeurs du middleware classique : credentials activés, en-têtes et méthodes de l’ancienne liste, max-age 60

Copier le code
AEngine.Use(CORSHTTPFilter('*', True, '',
  'Content-Type, Accept, jwtusername, jwtpassword, authentication, authorization',
  'POST,GET,OPTIONS,PUT,DELETE,PATCH', 60));

Le filtre répond au preflight avant le routing et ajoute aussi les en-têtes aux réponses d’erreur : un 404 porte Access-Control-Allow-Origin.

ETag

Le filtre écrit l’ETag entre guillemets, comme le demande la RFC 7232, accepte le préfixe W/ dans If-None-Match et n’agit que sur les réponses 2xx. Le middleware classique écrit le digest SHA-1 sans guillemets et le compare tel quel à If-None-Match. Si l’action a déjà défini un ETag, le classique le laisse, le filtre le remplace par le sien. Dans les deux cas, seules les réponses qui ont un ContentStream reçoivent l’ETag : une réponse sous forme de chaîne ne le reçoit pas.

Redirect

Le filtre répond 302 (301 avec rdkPermanent, le troisième paramètre) et conserve la query string ; avec rdqDrop, le quatrième paramètre, il la supprime : RedirectHTTPFilter(['/old'], '/new', rdkPermanent, rdqDrop). Il compare le chemin sans tenir compte de la casse ; le middleware compare le texte exact.

Analytics

Le fichier CSV a les mêmes colonnes. La cinquième, qui dans le middleware contient controller et action, contient dans le filtre le PathInfo : un filtre HTTP n’a pas de controller à nommer.

Swagger

SwaggerHTTPFilter se trouve dans MVCFramework.Filters.Swagger et génère le document avec le même code que TMVCSwaggerMiddleware, désormais déprécié ; OpenAPIHTTPFilter se trouve dans MVCFramework.Filters.OpenAPI. L’authentification JWT est cherchée au moment où le document est généré, une fois la requête reçue, donc l’ordre d’enregistrement ne compte pas. La recherche ne trouve toutefois que le middleware classique, TMVCJWTAuthenticationMiddleware : avec JWTAuthenticationBundle, le schéma Bearer n’apparaît que si tu le demandes avec [sauBearer], et la route de login n’apparaît pas dans le document.

Les deux authentifications du document, Basic et Bearer, sont dans le middleware deux Boolean, le cinquième et le dixième paramètre. Dans le filtre, elles forment un set en cinquième position, [sauBasic, sauBearer], et le filtre a donc un paramètre de moins : si tu recopies les arguments du middleware un à un, le compilateur s’arrête sur le cinquième. Le wizard passe [sauBearer] quand le projet utilise JWT en en-tête, sinon [].

Sessions

Les deux Boolean des middleware de session, HttpOnly et Secure, deviennent dans les filtres un set, TMVCSessionCookieFlags, qui vaut par défaut [scfHttpOnly]. Il ne suffit donc pas de changer le nom de la fonction :

UseFileSessionMiddleware(10, True, ‘sessions’, True) devient FileSessionHTTPFilter(10, ‘sessions’, [scfHttpOnly, scfSecure]) : les deux Boolean deviennent un set de flags

Copier le code
// before
AEngine.AddMiddleware(UseFileSessionMiddleware(10, True, 'sessions', True));

// after
AEngine.Use(FileSessionHTTPFilter(10, 'sessions', [scfHttpOnly, scfSecure]));

Si tu copies les paramètres un à un, le compilateur proteste, parce que là où il y avait un Boolean il y a maintenant un set. Pour construire le set à partir d’un Boolean, il y a SessionCookieFlags : il a toujours HttpOnly, et Secure seulement si le paramètre est vrai. C’est ce qu’utilise le code généré par le wizard.

Pour n’importe quelle session factory, il y a SessionHTTPFilter(factory), et SessionEndpointFilter(factory) pour les groupes Minimal API : le filtre en devient propriétaire. MemorySessionHTTPFilter, FileSessionHTTPFilter et DatabaseSessionHTTPFilter sont construits dessus, et ce dernier se trouve dans MVCFramework.Filters.ActiveRecord.

Boolean et enum

Dans les signatures des filtres, j’ai évité les Boolean quand le True ne s’explique pas tout seul, la boolean trap. Dans UseFileSessionMiddleware(10, True, 'sessions', True), celui qui lit ne sait pas quel True est HttpOnly et lequel est Secure, et doit ouvrir la déclaration. Les filtres de session prennent à la place le set TMVCSessionCookieFlags, qui se lit tout seul : [scfHttpOnly, scfSecure]. Il en va de même pour les autres filtres :

  • RedirectHTTPFilter distingue 302 et 301 avec TMVCRedirectKind (rdkTemporary, rdkPermanent) et conserve ou supprime la query string avec TMVCRedirectQuery (rdqPreserve, rdqDrop) ;
  • TraceHTTPFilter prend le set TMVCTraceFlags (tfLogAuthorization, tfLogNonTextBody) ;
  • SwaggerHTTPFilter prend le set TMVCSwaggerAuthentications (sauBasic, sauBearer) ;
  • les options de StaticFilesHTTPFilter ont Mode (sfmFiles, sfmSPA) et Flags (sffCaseSensitivePrefix).

Deux paramètres restent des Boolean. AAllowsCredentials de CORSHTTPFilter reprend le paramètre du même nom du middleware CORS, pour que les deux styles s’écrivent de la même façon. SessionCookieFlags(ASecure) convertit en flags une valeur lue à l’exécution dans le fichier .env, comme le fait le code du wizard.

Rate limit

La forme simple, RateLimitHTTPFilter(10, 60), existe toujours. Pour les options, on prépare un TMVCRateLimitOptions, comme le fait le code généré par le wizard :

RateLimitHTTPFilter avec TMVCRateLimitOptions : 10 requêtes en 60 secondes, chemin /health exclu, callback OnExceeded qui écrit dans le log

Copier le code
lRateLimitOptions := TMVCRateLimitOptions.Default;
lRateLimitOptions.MaxRequests := 10;
lRateLimitOptions.WindowSeconds := 60;
lRateLimitOptions.ExcludedPaths := ['/health'];
lRateLimitOptions.OnExceeded :=
  procedure(const AContext: TWebContext; const AKey: string;
    const ALimit: Integer; const AWindowSeconds: Integer)
  begin
    LogW(Format('Rate limit exceeded for key: %s (Limit: %d requests per %d seconds)',
      [AKey, ALimit, AWindowSeconds]));
  end;
AEngine.Use(RateLimitHTTPFilter(lRateLimitOptions));

StaticFiles

La forme simple, StaticFilesHTTPFilter('/static', lWwwPath), et celle avec les options, StaticFilesHTTPFilter(TMVCStaticFilesOptions), sont la même implémentation. La différence principale par rapport à TMVCStaticFilesMiddleware est le fallback pour les single page applications : dans le middleware il était actif par défaut, dans le filtre il est désactivé. Dans la forme simple, on l’active avec sfmSPA :

StaticFilesHTTPFilter sur / avec sfmSPA, pour une single page application avec l’API à côté

Copier le code
AEngine.Use(StaticFilesHTTPFilter('/', 'www/app', sfmSPA));

Avec sfmSPA, le filtre laisse passer la requête au routeur, et répond avec l’index.html du dossier existant le plus proche seulement à un GET ou HEAD pour lequel l’application n’a aucune route. Les routes de l’API ne sont jamais masquées, donc la SPA peut se trouver à / avec l’API à côté. Avec les options, on définit Mode := sfmSPA ; dans TMVCStaticFilesOptions.Default, il vaut sfmFiles. Le troisième paramètre de la forme simple est le mode (sfmFiles ou sfmSPA), le document d’index, index.html par défaut, est le quatrième.

Deux limites. Il faut AllowUnhandledAction = false, qui est la valeur par défaut. Et le routeur continue d’écrire dans le log “ROUTE NOT FOUND” pour chaque route côté client.

Le reste est comme dans le middleware : le préfixe ne tient pas compte de la casse (avec sffCaseSensitivePrefix dans Flags, il en tient compte), avec ou sans / final, les fichiers sont servis avec leur type MIME et Last-Modified (et 304 sur If-Modified-Since), un dossier sans / final répond 301 puis sert son index.html. Il reste deux différences. Le middleware écrivait dans le log une ligne pour chaque fichier servi, avec méthode, statut, chemin, IP et durée, et les filtres non. Le filtre sert .webp, .woff, .woff2 et .ttf avec le bon type, des extensions que le middleware ne connaissait pas. Les autres options du middleware, le charset, les types MIME personnalisés et les règles par requête, s’obtiennent avec TMVCStaticFilesOptions.

Si tu as aussi besoin des requêtes Range, pour l’audio et la vidéo, il y a FileServerBundle, celui que le wizard utilise pour /static. La forme est la même, avec les modes fsmFiles et fsmSPA : FileServerBundle('/', 'www/app', fsmSPA).

Compression

Le seuil de 1024 octets, le niveau de compression et le choix de l’encodage (le premier entre gzip et deflate dans l’ordre de l’en-tête Accept-Encoding) sont ceux du middleware. Une chose change : le filtre ne recompresse pas une réponse qui a déjà un Content-Encoding. RangeMediaHTTPFilter en définit un identity sur les réponses partielles, et les compresser casserait Content-Range.

Les autres

TraceHTTPFilter se comporte comme le middleware. Chaque ligne de log porte l’id de corrélation [rid:...], et le même id revient dans l’en-tête de réponse X-Request-ID : c’est celui de l’appelant s’il y en a un, sinon il en génère un de six chiffres hexadécimaux. Authorization apparaît avec le schéma et trois astérisques, Bearer ***, et les en-têtes de réponse Authorization, Proxy-Authorization, Cookie et Set-Cookie sont masqués. Le body est enregistré jusqu’à 1024 octets. La signature a un paramètre que le middleware n’a pas, le troisième : TraceHTTPFilter(AMaxBodySize, ALogTag, AFlags, ACorrelationHeaderName). AFlags est un set, vide par défaut : avec tfLogAuthorization, l’Authorization de la requête s’écrit en clair, avec tfLogNonTextBody, les body qui ne sont pas du texte sont aussi enregistrés. Le nom de l’en-tête, X-Request-ID par défaut, était le troisième paramètre dans le middleware et c’est maintenant le quatrième : si tu le passais, le compilateur te le signale.

SecurityHeadersHTTPFilter écrit les deux mêmes en-têtes que le middleware, X-XSS-Protection: 0 et X-Content-Type-Options: nosniff, et n’a pas de paramètres. ShutdownHTTPFilter ne répond qu’aux POST sur /api/shutdown, comme avant. RangeMediaHTTPFilter et OpenAPIHTTPFilter ont les mêmes valeurs que le middleware, et OpenAPIHTTPFilter sert le document sur /openapi.json. ActiveRecordHTTPFilter lit FDConnectionDefs.ini comme le middleware, mais il est écrit nativement et libère la connexion dans un finally autour de ANext().

J’ai comparé les valeurs par défaut en lisant le code source du middleware et du filtre. Si tu trouves une différence que je n’ai pas listée, ouvre une issue.


Les filtres d’endpoint

La seconde responsabilité du middleware classique, contrôler la manière dont les actions sont exécutées, revient au filtre d’endpoint. Un filtre d’endpoint est cette fonction :

Signature d’un filtre d’endpoint : une fonction avec AContext de type TWebContext et ANext de type TMVCEndpointFilterNext qui renvoie un IMVCResponse

Copier le code
function(const AContext: TWebContext; const ANext: TMVCEndpointFilterNext): IMVCResponse

Il s’exécute après le routing, quand le framework sait déjà quelle action ou quelle route Minimal API va répondre. Comme dans le filtre HTTP, le code avant ANext() s’exécute avant l’action, et celui qui suit, une fois l’action terminée. Contrairement au filtre HTTP, c’est une fonction, et elle renvoie un IMVCResponse.

Quand il s’exécute

Pour voir l’ordre, j’ai mis sur le même serveur un filtre HTTP, un middleware classique avec ses quatre méthodes, un filtre d’endpoint enregistré sur l’engine, un controller et une route Minimal API, et j’ai fait écrire à chacun une ligne dans la console. Voici un GET sur l’action du controller :

HTTP filter: before ANext()
  MW  OnBeforeRouting
  MW  OnBeforeControllerAction(PipelineOrder.TOrderController, Hello)
    EF  engine endpoint filter: before ANext(), ControllerQualifiedClassName="PipelineOrder.TOrderController", ActionName="Hello", Params[id]="42"
      ACTION TOrderController.Hello(id=42)
    EF  engine endpoint filter: after ANext(), ANext() returned nil, Response.StatusCode=200
  MW  OnAfterControllerAction(PipelineOrder.TOrderController, Hello, AHandled=False)
  MW  OnAfterRouting(AHandled=False)
HTTP filter: after ANext(), Response.StatusCode=200

Et voici un GET sur la route Minimal API, qui a aussi un filtre sur son groupe, /min :

HTTP filter: before ANext()
  MW  OnBeforeRouting
    EF  engine endpoint filter: before ANext(), ControllerQualifiedClassName="", ActionName="GET /min/hello/($id)", Params[id]="42"
     GF  group endpoint filter (/min): before ANext()
      HANDLER Minimal API GET /min/hello/($id) (id=42)
     GF  group endpoint filter (/min): after ANext()
    EF  engine endpoint filter: after ANext(), ANext() returned IMVCResponse status 200, Response.StatusCode=200
  MW  OnAfterRouting(AHandled=True)
HTTP filter: after ANext(), Response.StatusCode=200

Dans la sortie, on voit que :

  • les filtres d’endpoint s’exécutent après tous les OnBeforeControllerAction des middleware classiques, et leur partie après ANext() se termine avant tous les OnAfterControllerAction, quel que soit l’ordre d’enregistrement ;
  • une route Minimal API ne passe ni par OnBeforeControllerAction ni par OnAfterControllerAction, parce que la Minimal API s’exécute dans l’OnBeforeRouting de son propre middleware, alors que le filtre d’endpoint s’exécute dans les deux cas ;
  • ANext() renvoie nil pour l’action d’un controller, qui a déjà écrit la réponse, et l’IMVCResponse du handler pour une route Minimal API, qui est écrit ensuite.

Une requête qui n’atteint aucune route, un 404 ou un fichier statique servi par un filtre HTTP, ne passe pas par les filtres d’endpoint. Si tu gardes des middleware classiques dans un projet Minimal API, ceux qui sont ajoutés après le premier appel à Root ou à Prefix ne reçoivent même pas OnBeforeRouting pour les routes de la Minimal API.

Arrêter la requête, et le code après l’action

Pour arrêter la requête, tu renvoies une réponse sans appeler ANext(). Ce filtre répond 400 quand un en-tête manque, et l’action ne s’exécute pas :

Filtre d’endpoint qui répond 400 avec BadRequest quand un en-tête manque, et n’appelle ANext que si l’en-tête est présent

Copier le code
function RequireHeaderEndpointFilter(const AHeaderName: string): TMVCEndpointFilter;
begin
  Result :=
    function(const AContext: TWebContext; const ANext: TMVCEndpointFilterNext): IMVCResponse
    begin
      if AContext.Request.Headers[AHeaderName].Trim.IsEmpty then
        Exit(BadRequest('Missing header ' + AHeaderName)); // no ANext(): the action does not run
      Result := ANext();
    end;
end;

Sur un controller, la réponse renvoyée par le filtre sort toujours en JSON, quel que soit le type de contenu du controller. Les OnAfterControllerAction des middleware classiques s’exécutent quand même, avec AHandled = True.

Le code après ANext() fait le travail de OnAfterControllerAction. Ce filtre écrit dans le log quelle action s’est exécutée et combien de temps elle a pris :

Filtre d’endpoint qui mesure avec TStopwatch la durée de l’action et écrit dans le log, dans un finally, le controller, l’action et les millisecondes

Copier le code
function ActionTimingEndpointFilter: TMVCEndpointFilter;
begin
  Result :=
    function(const AContext: TWebContext; const ANext: TMVCEndpointFilterNext): IMVCResponse
    var
      lWatch: TStopwatch;
    begin
      lWatch := TStopwatch.StartNew;
      try
        Result := ANext();
      finally
        // runs even when the action raises
        // ControllerQualifiedClassName is '' for a Minimal API route, ActionName is then 'GET /pattern'
        LogI(Format('%s %s took %d ms',
          [AContext.ControllerQualifiedClassName, AContext.ActionName, lWatch.ElapsedMilliseconds]));
      end;
    end;
end;

Le finally est là parce qu’une exception levée par l’action passe par ANext() : le filtre d’endpoint la voit, et avec try..finally son code s’exécute quand même, avec try..except il peut l’observer. Dans ce cas, OnAfterControllerAction est sauté. Dans un filtre HTTP, cela ne se produit pas : l’engine a déjà géré l’exception et répondu 500, et le code après ANext() s’exécute sans avoir besoin d’un finally.

Où l’enregistrer

OùCommentPour quelles requêtes
EngineAEngine.Use(filter)chaque action des controllers et chaque route Minimal API
Groupe Minimal APIlGroup := lGroup.Use(filter)les routes mappées ensuite sur le groupe et sur les groupes imbriqués
Une routelGroup.MapGet(...).Use(filter)cette route uniquement

Deux filtres d’endpoint enregistrés sur l’engine avec AEngine.Use, et un sur un groupe Minimal API /api/v1 en gardant le groupe renvoyé par Use

Copier le code
// every controller action and every Minimal API route
AEngine
  .Use(ActionTimingEndpointFilter())                // the first registered is the outermost: it also times the check
  .Use(RequireHeaderEndpointFilter('X-Tenant-ID'));

// or only the routes of /api/v1 and of the groups nested in it;
// a group is an immutable record: keep what Use returns, and call Use before MapXxx
lApi := AEngine.Prefix('/api/v1').Use(RequireHeaderEndpointFilter('X-Tenant-ID'));

Le premier enregistré est le plus extérieur. Une route Minimal API passe d’abord par les filtres de l’engine, puis par ceux des groupes, en partant du plus extérieur, puis par ceux de la route. Tous les filtres HTTP se trouvent à l’extérieur de tous les filtres d’endpoint.

Le groupe est un record immuable, et deux erreurs sont vite arrivées. lGroup.Use(F); sans affecter le résultat ne fait rien, parce que Use renvoie un nouveau groupe. Et chaque route copie les filtres du groupe au moment où tu la mappes : un Use après MapGet n’atteint donc pas les routes déjà mappées.

Il n’y a pas de Use pour un seul controller, ni d’attribut. Un filtre qui ne concerne qu’un controller vérifie AContext.ControllerQualifiedClassName et, pour tous les autres, se contente d’appeler ANext().

Ce qu’il voit

Après le routing, le filtre sait à quoi correspond la requête. Dans le test de tout à l’heure, avec /ctrl/hello/42 et /min/hello/42 :

Action d’un controllerRoute Minimal API
AContext.ControllerQualifiedClassNamePipelineOrder.TOrderControllervide
AContext.ActionNameHelloGET /min/hello/($id)
AContext.Request.Params['id']4242

AContext.LoggedUser est renseigné si un filtre d’authentification a déjà reconnu l’utilisateur. Le filtre ne voit ni les attributs de l’action ni l’instance du controller.

Des deux hooks au filtre d’endpoint

Un middleware qui utilise OnBeforeControllerAction et OnAfterControllerAction se transforme ainsi en filtre d’endpoint : le premier devient le code avant ANext(), le second le code après, et AHandled := True une réponse renvoyée sans appeler ANext(). Le filtre s’exécute aussi pour les routes Minimal API, et avec un finally sa partie après s’exécute même quand l’action lève une exception.

Les filtres d’endpoint prêts à l’emploi

FiltreCe qu’il fait
AuthorizeEndpointFilter()401 si aucun filtre d’authentification n’a reconnu l’utilisateur
RequireRoleEndpointFilter('admin')401 sans utilisateur, 403 si l’utilisateur n’a aucun des rôles
BasicAuthEndpointFilter(...)authentification Basic : 401 avec WWW-Authenticate, 403 si l’utilisateur n’est pas autorisé
CORSEndpointFilter(...)en-têtes CORS sur les réponses des routes
CSRFEndpointFilter(...)contrôle CSRF sur les requêtes qui ont une route
SessionEndpointFilter, MemorySessionEndpointFilter, FileSessionEndpointFilter, DatabaseSessionEndpointFiltersessions
ActiveRecordEndpointFilter('conn_def_name')connexion ActiveRecord autour de l’action

Ils s’appliquent aux controllers, avec AEngine.Use, et aux groupes Minimal API. Pour toute une API, en revanche, CORS et les sessions s’enregistrent comme filtres HTTP. CORSEndpointFilter ne répond au preflight que sur une route enregistrée pour OPTIONS, alors que CORSHTTPFilter répond à tous. Et une session enregistrée comme filtre d’endpoint arrive après les filtres HTTP et après tous les OnBeforeControllerAction, trop tard pour un login qui s’en sert.


Les bundles

Certains mécanismes ont besoin des deux types de filtre. JWT est le cas typique : le login n’a pas besoin d’une route, c’est donc un filtre HTTP, alors que le contrôle du token doit savoir quelle action va s’exécuter, c’est donc un filtre d’endpoint. N’en enregistrer qu’une moitié, ou enregistrer les deux moitiés avec des paramètres différents, était une erreur de configuration que le compilateur ne voyait pas. C’est pour cela que les deux moitiés se trouvent dans un bundle :

L’interface IMVCFilterBundle déclarée dans MVCFramework.pas : deux fonctions, HTTPFilters et EndpointFilters

Copier le code
IMVCFilterBundle = interface
  ['{35D2589D-F40A-426D-925F-87A7722A88C8}']
  function HTTPFilters: TArray<TMVCHTTPFilter>;
  function EndpointFilters: TArray<TMVCEndpointFilter>;
end;

AEngine.Use(bundle) place les filtres HTTP du bundle dans la chaîne des filtres HTTP et ses filtres d’endpoint dans la chaîne des filtres d’endpoint, tous à l’endroit de l’appel et dans leur ordre. FileServerBundle, celui des fichiers statiques, est un bundle qui n’a que la partie HTTP.

Les bundles d’authentification

BundlePartie HTTPPartie d’endpointMiddleware qu’il remplace
JWTAuthenticationBundlelogin ; blacklist et refresh token, si tu les configurescontrôle du token dans Authorization: BearerTMVCJWTAuthenticationMiddleware, TMVCJWTBlackListMiddleware, TMVCJWTRefreshTokenMiddleware
JWTCookieAuthenticationBundlelogin et logout, avec le contrôle de l’Origin du login (LoginAllowedOrigins)contrôle du token dans le cookieTMVCJWTCookieAuthenticationMiddleware
BasicAuthenticationBundleaucuneBasicAuthEndpointFilterTMVCBasicAuthenticationMiddleware
CustomAuthenticationBundlelogin et logout sur /system/users/loggedcontrôle de la sessionTMVCCustomAuthenticationMiddleware, TMVCRoleBasedAuthMiddleware (avec TRoleBasedAuthHandler)
OIDCAuthenticationBundlelogin, callback et logoutsession valide, sinon 302 vers le loginTMVCOIDCAuthenticationMiddleware

Les quatre premiers se trouvent dans MVCFramework.Filters.Authentication, OIDCAuthenticationBundle dans MVCFramework.Filters.OIDC. CSRF n’a pas de bundle mais deux filtres : CSRFHTTPFilter contrôle avant le routing, comme le middleware, CSRFEndpointFilter après.

Le bundle et le middleware déprécié exécutent le même code : la logique se trouve dans les units des filtres, et le middleware n’est plus qu’une fine enveloppe autour d’elle, avec l’API de la 3.4. Avec le même IMVCAuthenticationHandler, le bundle contrôle et répond donc comme le middleware. Comme les dix-sept, les middleware d’authentification continueront de fonctionner jusqu’à la 4.0 exclue, et l’avertissement du compilateur nomme le bundle à utiliser : pour TMVCJWTAuthenticationMiddleware, c’est AEngine.Use(JWTAuthenticationBundle(...)).

La forme courte du bundle JWT :

JWTAuthenticationBundle enregistré avec AEngine.Use : handler d’authentification, méthode anonyme qui définit les claims du token, et secret

Copier le code
AEngine.Use(JWTAuthenticationBundle(TMyAuthHandler.Create,
  procedure(const AJWT: TJWT)
  begin
    AJWT.Claims.Issuer := 'my-server';
    AJWT.Claims.ExpirationTime := IncHour(Now, 1);
    AJWT.Claims.NotBefore := IncMinute(Now, -5);
    AJWT.Claims.IssuedAt := Now;
  end,
  lSecret));

Je l’ai testé sur Indy Direct. POST /login avec les en-têtes jwtusername et jwtpassword répond 200 avec {"token":"eyJ..."}, et 401 avec un mauvais mot de passe. À partir de là, chaque action et chaque route Minimal API demande le token, sauf les actions que le handler rend publiques dans OnRequest : sur les routes Minimal API, OnRequest n’est pas appelé, et le token est toujours nécessaire. Sans token, un controller répond 401 avec {"classname":"","message":"Authorization Required"}, une route Minimal API 401 avec un application/problem+json.

Avec les options, tu actives le refresh token : il suffit d’assigner un store.

JWTAuthenticationBundle avec TMVCJWTAuthenticationOptions : handler, secret, URL de login, durée de vie du token et store des refresh tokens

Copier le code
lOptions := TMVCJWTAuthenticationOptions.Default;
lOptions.Handler := TMyAuthHandler.Create;
lOptions.Secret := lSecret;
lOptions.LoginURL := '/auth/login';
lOptions.RefreshToken.Issuer := 'my-server';
lOptions.RefreshToken.AccessTokenTTLSeconds := 15 * 60;
// a store turns the refresh token on; one store for the whole process
lOptions.RefreshTokenStore := gRefreshStore;
AEngine.Use(JWTAuthenticationBundle(lOptions));

Le store est unique pour tout le processus et se crée dans initialization avec TMVCInMemoryRefreshTokenStore.Create : sous WebBroker, ISAPI et Apache, chaque web module a son propre engine. Le login, un POST /auth/login avec {"username":...,"password":...}, répond avec access_token, refresh_token, token_type et expires_in. POST /auth/refresh renvoie une nouvelle paire. Si le même refresh token arrive une seconde fois, la réponse est 401 avec {"error": "Refresh token reuse detected; session revoked"}.

CustomAuthenticationBundle doit être enregistré après un filtre HTTP de session, par exemple MemorySessionHTTPFilter : le middleware de session classique s’exécute après tous les filtres HTTP, trop tard pour le login.

Un bundle sur un groupe Minimal API

Sur un groupe, Use met la partie HTTP sur l’engine et la partie d’endpoint sur le groupe :

Groupe Minimal API /api/v1 avec une route publique et un groupe imbriqué /admin avec JWTAuthenticationBundle et RequireRoleEndpointFilter

Copier le code
lApi := AEngine.Prefix('/api/v1');
lApi.MapGet('/products',
  function: IMVCResponse
  begin
    Result := Ok('the product list'); // no token needed here
  end);

// login on the engine (it answers before routing), token and role checked on /api/v1/admin only
lAdmin := lApi.Prefix('/admin')
  .Use(JWTAuthenticationBundle(TMyAuthHandler.Create, lClaimsSetup, lSecret, '/api/v1/admin/login'))
  .Use(RequireRoleEndpointFilter('admin'));
lAdmin.MapGet<TWebContext>('/stats',
  function(AContext: TWebContext): IMVCResponse
  begin
    Result := Ok('stats for ' + AContext.LoggedUser.UserName);
  end);

Le login sur /api/v1/admin/login répond avant le routing, même s’il n’y a aucune route à cette adresse. /api/v1/admin/stats répond 401 sans token, 403 avec le token d’un utilisateur qui n’a pas le rôle admin, et 200 avec celui d’un administrateur. /api/v1/products, en dehors de /admin, ne demande rien.

Ici aussi, garde le résultat de Use : si tu l’ignores, le login reste sur l’engine et les routes du groupe ne contrôlent pas le token.

Ton propre bundle

TMVCFilterBundle implémente l’interface et contient les deux listes. Il n’a pas de méthodes virtuelles à redéfinir : ton bundle est une fonction qui le crée avec tes filtres, comme le fait le framework avec FileServerBundle et avec les bundles d’authentification. Celui-ci donne un id à chaque réponse, y compris aux 404 et aux fichiers statiques, et écrit une ligne d’audit avec le même id uniquement pour les requêtes qui atteignent une action :

Bundle écrit à la main : RequestIdHTTPFilter met un id sur chaque réponse, AuditEndpointFilter écrit une ligne de log pour les actions, RequestAuditBundle les réunit avec TMVCFilterBundle.Create

Copier le code
const
  REQUEST_ID = 'request_id';

// HTTP part: every response gets an id, 404s and static files included
function RequestIdHTTPFilter(const AHeaderName: string): TMVCHTTPFilter;
begin
  Result :=
    procedure(const AContext: TWebContext; const ANext: TMVCHTTPFilterNext)
    var
      lId: string;
    begin
      lId := AContext.Request.Headers[AHeaderName];
      if lId.IsEmpty then
        lId := TGUID.NewGuid.ToString;
      AContext.Data[REQUEST_ID] := lId;
      AContext.Response.SetCustomHeader(AHeaderName, lId);
      ANext();
    end;
end;

// endpoint part: an audit line, with the same id, for the requests that reach an action
function AuditEndpointFilter: TMVCEndpointFilter;
begin
  Result :=
    function(const AContext: TWebContext; const ANext: TMVCEndpointFilterNext): IMVCResponse
    begin
      LogI(Format('[%s] %s %s by "%s"', [AContext.Data[REQUEST_ID],
        AContext.ControllerQualifiedClassName, AContext.ActionName, AContext.LoggedUser.UserName]));
      Result := ANext();
    end;
end;

function RequestAuditBundle(const AHeaderName: string = 'X-Request-ID'): IMVCFilterBundle;
begin
  Result := TMVCFilterBundle.Create([RequestIdHTTPFilter(AHeaderName)], [AuditEndpointFilter()]);
end;

Il s’enregistre avec AEngine.Use(RequestAuditBundle()).

Use vérifie la configuration au démarrage et lève EMVCConfigException si tu enregistres deux fois la même instance d’un bundle, si tu l’enregistres sur l’engine et sur un groupe, ou si tu mets sur un groupe un bundle sans partie d’endpoint, comme FileServerBundle. La vérification porte sur l’instance : deux appels à JWTAuthenticationBundle(...) créent deux bundles, donc deux logins et deux contrôles.


Questions fréquentes

Pourquoi DelphiMVCFramework ajoute-t-il les filtres HTTP à côté des middleware ? Le middleware classique avait deux responsabilités : influencer le routing et contrôler la manière dont les actions sont exécutées. Le filtre HTTP sépare la première grâce au mécanisme du next, le même qu’Express, Koa, ASP.NET Core, Laravel, Starlette, FastAPI, Gin et axum : une procédure qui reçoit le contexte et ANext, et décide si et quand passer la requête à ce qui vient après. La seconde responsabilité revient au filtre d’endpoint, qui s’exécute après le routing.

Quels middleware de DelphiMVCFramework sont dépréciés ? Dix-sept middleware, quatorze classes et trois fonctions de création : TMVCRedirectMiddleware, TMVCStaticFilesMiddleware, TMVCAnalyticsMiddleware, TMVCTraceMiddleware, TMVCCompressionMiddleware, TMVCETagMiddleware, TMVCCORSMiddleware, TMVCSecurityHeadersMiddleware, TMVCShutdownMiddleware, TMVCRangeMediaMiddleware, TMVCSwaggerMiddleware, TMVCOpenAPI3Middleware, TMVCRateLimitMiddleware, TMVCActiveRecordMiddleware et les fonctions UseMemorySessionMiddleware, UseFileSessionMiddleware, UseDatabaseSessionMiddleware. Chacun a un filtre HTTP dans MVCFramework.Filters (RedirectHTTPFilter, StaticFilesHTTPFilter, AnalyticsHTTPFilter, TraceHTTPFilter, CompressionHTTPFilter, ETagHTTPFilter, CORSHTTPFilter, SecurityHeadersHTTPFilter, ShutdownHTTPFilter, RangeMediaHTTPFilter, SwaggerHTTPFilter, OpenAPIHTTPFilter, RateLimitHTTPFilter, ActiveRecordHTTPFilter, MemorySessionHTTPFilter, FileSessionHTTPFilter, DatabaseSessionHTTPFilter), qui s’enregistre avec AEngine.Use. ActiveRecordHTTPFilter et DatabaseSessionHTTPFilter se trouvent dans MVCFramework.Filters.ActiveRecord, SwaggerHTTPFilter dans MVCFramework.Filters.Swagger et OpenAPIHTTPFilter dans MVCFramework.Filters.OpenAPI : si tu les utilises, ajoute l’unit à la uses. Les middleware d’authentification sont dépréciés eux aussi (JWT en en-tête et en cookie, blacklist, refresh token, Basic, authentification personnalisée, RoleBased, OIDC, CSRF) : ils ont leurs propres filtres, en partie HTTP et en partie d’endpoint.

Mon serveur existant cesse-t-il de fonctionner ? Non, pas dans la branche 3.5. Rien n’a été supprimé. Le compilateur affiche l’avertissement W1000 pour chaque middleware déprécié que tu utilises, et le code compile et tourne comme avant.

Que deviennent les middleware dans la 4.0 ? Ils seront supprimés complètement. Jusqu’à la 4.0 exclue, ils continuent de fonctionner, avec un avertissement du compilateur. Tous les middleware dépréciés ont déjà leur filtre et se remplacent dès aujourd’hui : les dix-sept de cet article par un filtre HTTP, ceux d’authentification par un bundle (JWTAuthenticationBundle et les autres).

Puis-je utiliser sessions, ActiveRecord et rate limit comme filtres dans les controllers ? Oui. MemorySessionHTTPFilter, FileSessionHTTPFilter, DatabaseSessionHTTPFilter, ActiveRecordHTTPFilter et RateLimitHTTPFilter avec TMVCRateLimitOptions sont des filtres HTTP, ils s’appliquent donc aux controllers. DatabaseSessionHTTPFilter doit être enregistré après ActiveRecordHTTPFilter. Le wizard les génère à la place des middleware classiques.

Et les middleware de JWT, Basic, OIDC et CSRF ? Ils sont dépréciés et ont leurs bundles : JWTAuthenticationBundle, JWTCookieAuthenticationBundle, BasicAuthenticationBundle, CustomAuthenticationBundle et OIDCAuthenticationBundle. Login, logout, callback et blacklist sont la partie HTTP du bundle, le contrôle de la requête est la partie d’endpoint, qui s’exécute après le routing parce que l’autorisation des controllers repose sur le nom du controller et de l’action. CSRF a deux filtres, CSRFHTTPFilter et CSRFEndpointFilter. Les middleware continuent de fonctionner jusqu’à la 4.0 exclue.

Qu’est-ce qu’un filtre d’endpoint et quand s’exécute-t-il ? C’est une fonction qui reçoit AContext et ANext et renvoie un IMVCResponse. Il s’exécute après le routing, aussi bien pour les actions des controllers que pour les routes Minimal API (sur un controller, après tous les OnBeforeControllerAction des middleware classiques), et il connaît le nom du controller, celui de l’action et les paramètres de la route. Il s’enregistre avec AEngine.Use pour tout le serveur, ou bien sur un groupe ou sur une seule route Minimal API.

Qu’est-ce qu’un bundle de filtres ? Un IMVCFilterBundle est un ensemble de filtres HTTP et de filtres d’endpoint qu’un seul Use enregistre dans le bon ordre. Les bundles d’authentification mettent le login dans la partie HTTP et le contrôle dans la partie d’endpoint ; FileServerBundle n’a que la partie HTTP. Sur un groupe Minimal API, la partie HTTP va sur l’engine et la partie d’endpoint sur le groupe. Un bundle personnalisé est une fonction qui renvoie TMVCFilterBundle.Create avec les deux listes de filtres.

Dans quel ordre enregistre-t-on les filtres et les middleware ? Par rapport à AddMiddleware, l’ordre ne compte pas : les filtres enveloppent de toute façon les middleware classiques. Entre les filtres, le premier enregistré est le plus extérieur, ETagHTTPFilter va avant CompressionHTTPFilter, et ActiveRecordHTTPFilter et les filtres de session se trouvent au point le plus intérieur.

Qu’est-ce qui change dans les valeurs par défaut de CORS en passant à CORSHTTPFilter ? Le filtre démarre avec les credentials désactivés, les en-têtes Content-Type,Authorization, les méthodes GET,POST,PUT,DELETE,PATCH,OPTIONS et un max-age de 1728000 secondes. Le middleware classique démarrait avec les credentials actifs, une liste d’en-têtes plus longue et les mêmes méthodes dans un autre ordre. Si tu as besoin des anciennes valeurs, passe-les comme paramètres à CORSHTTPFilter.

Qu’est-ce qui change, en plus de CORSHTTPFilter, dans les valeurs par défaut des filtres par rapport aux middleware ? Le fallback pour les single page applications de StaticFilesHTTPFilter est désactivé par défaut, alors que dans le middleware il était actif : on l’active avec StaticFilesHTTPFilter('/', folder, sfmSPA) ou avec Mode := sfmSPA dans les options de TMVCStaticFilesOptions, et le routeur décide, donc les routes de l’API ne sont pas masquées et la SPA peut aussi se trouver sur /. Le filtre n’écrit pas la ligne de log pour chaque fichier servi qu’écrivait le middleware, et CompressionHTTPFilter ne compresse pas une réponse qui a déjà un Content-Encoding. TraceHTTPFilter, SecurityHeadersHTTPFilter, ShutdownHTTPFilter, OpenAPIHTTPFilter, RangeMediaHTTPFilter et ActiveRecordHTTPFilter ont les mêmes valeurs par défaut que les middleware.


Ressources

– Daniele Teti

Faits clés
  • Sujet : la différence entre les middleware classiques (IMVCMiddleware, AddMiddleware) et les filtres HTTP (TMVCHTTPFilter, enregistrés avec AEngine.Use) dans DelphiMVCFramework, le framework REST et web pour Delphi, et comment migrer. Branche 3.5.0-silicon ; ce sera dans la RC9 (3.5.0-silicon-rc9). Le travail décrit n'est pas encore dans une release. L'article porte sur les filtres HTTP (avant le routing), les filtres d'endpoint (après le routing) et les bundles qui les enregistrent ensemble.
  • Ce n'est pas un breaking change : dans la 3.5.0-silicon, les filtres sont une fonctionnalité supplémentaire et les serveurs existants continuent de fonctionner de la même façon, avec un avertissement du compilateur (W1000) pour chaque middleware déprécié. Le breaking change est prévu dans la 4.0, où les middleware seront supprimés complètement. La transition est graduelle parce que DelphiMVCFramework est utilisé dans des environnements critiques (hôpitaux, banques, usines, jeux vidéo, ERP).
  • Pourquoi : le middleware classique avait deux responsabilités, influencer le routing (OnBeforeRouting, OnAfterRouting) et contrôler la manière dont les actions sont exécutées (OnBeforeControllerAction, OnAfterControllerAction). Le filtre HTTP sépare la première grâce au mécanisme du next, utilisé aussi par Express, Koa, ASP.NET Core, Laravel, Starlette, FastAPI, Gin et axum : une procédure (AContext, ANext) qui s'exécute avant le routing et enveloppe tout le dispatch ; elle s'applique aux controllers et à la Minimal API. OnBeforeRouting correspond au code avant ANext() ; OnAfterRouting, qui se déclenche à la toute fin, au code après ANext(), qui s'exécute aussi quand l'action lève une exception (l'engine répond 500 à l'intérieur de ANext()). La seconde responsabilité revient au filtre d'endpoint.
  • Les filtres HTTP prennent la place des middleware là où il en existe un équivalent. Dix-sept middleware sont marqués deprecated (avertissement W1000, pas une erreur), quatorze classes et trois fonctions : TMVCRedirectMiddleware, TMVCStaticFilesMiddleware, TMVCAnalyticsMiddleware, TMVCTraceMiddleware, TMVCCompressionMiddleware, TMVCETagMiddleware, TMVCCORSMiddleware, TMVCSecurityHeadersMiddleware, TMVCShutdownMiddleware, TMVCRangeMediaMiddleware, TMVCSwaggerMiddleware, TMVCOpenAPI3Middleware, TMVCRateLimitMiddleware, TMVCActiveRecordMiddleware, UseMemorySessionMiddleware, UseFileSessionMiddleware, UseDatabaseSessionMiddleware. Filtres : RedirectHTTPFilter, StaticFilesHTTPFilter, AnalyticsHTTPFilter, TraceHTTPFilter, CompressionHTTPFilter, ETagHTTPFilter, CORSHTTPFilter, SecurityHeadersHTTPFilter, ShutdownHTTPFilter, RangeMediaHTTPFilter, SwaggerHTTPFilter, OpenAPIHTTPFilter, RateLimitHTTPFilter (aussi avec TMVCRateLimitOptions), ActiveRecordHTTPFilter, MemorySessionHTTPFilter, FileSessionHTTPFilter, DatabaseSessionHTTPFilter (unit MVCFramework.Filters, sauf ActiveRecordHTTPFilter et DatabaseSessionHTTPFilter dans MVCFramework.Filters.ActiveRecord, SwaggerHTTPFilter dans MVCFramework.Filters.Swagger et OpenAPIHTTPFilter dans MVCFramework.Filters.OpenAPI, à ajouter aux uses). Le nom indique le type : il se termine par HTTPFilter, par EndpointFilter ou par Bundle. Une seule méthode de TMVCEngine, AEngine.Use, enregistre les filtres HTTP, les filtres d'endpoint et les bundles (IMVCFilterBundle, un ensemble de filtres placés dans le bon ordre) ; une fonction de filtre sans paramètres passée à Use demande les parenthèses, par exemple ETagHTTPFilter(). Rien n'a été supprimé. Par conséquent, le wizard des nouveaux projets génère les filtres à la place de ces middleware, et pour les fichiers statiques il utilise FileServerBundle, qui sert les fichiers comme StaticFilesHTTPFilter et répond aussi aux requêtes Range avec 206.
  • Les middleware d'authentification ont eux aussi leurs filtres et sont dépréciés : JWT (en-tête et cookie), blacklist, refresh token, Basic, authentification personnalisée, RoleBased, OIDC, CSRF. Login, logout, callback et blacklist sont des filtres HTTP ; le contrôle de la requête est un filtre d'endpoint (EndpointFilter), qui s'exécute après le routing parce que l'autorisation des controllers décide d'après le nom du controller et de l'action. Les deux moitiés de chaque mécanisme se trouvent dans un bundle enregistré avec un seul Use : JWTAuthenticationBundle, JWTCookieAuthenticationBundle, BasicAuthenticationBundle, CustomAuthenticationBundle (unit MVCFramework.Filters.Authentication) et OIDCAuthenticationBundle (MVCFramework.Filters.OIDC). Tous les middleware dépréciés continuent de fonctionner jusqu'à la 4.0 exclue ; dans la 4.0, ils seront supprimés complètement.
  • Filtres d'endpoint (TMVCEndpointFilter) : fonction (AContext, ANext) qui renvoie un IMVCResponse. Ordre vérifié sur Indy Direct : filtres HTTP, OnBeforeRouting, routing, tous les OnBeforeControllerAction, filtres d'endpoint, action, tous les OnAfterControllerAction, OnAfterRouting, filtres HTTP. Ils s'appliquent aux actions des controllers et aux routes Minimal API (qui ne passent ni par OnBeforeControllerAction ni par OnAfterControllerAction). ANext() renvoie nil pour un controller et l'IMVCResponse du handler pour une route. Ils s'enregistrent avec AEngine.Use (tout le serveur), sur un groupe Minimal API (lGroup := lGroup.Use(...), le groupe est un record immuable) ou sur une route ; il n'existe ni Use pour un seul controller ni attribut. Ils voient ControllerQualifiedClassName, ActionName et les paramètres de la route. Pour arrêter la requête, on renvoie une réponse sans appeler ANext() ; l'exception de l'action passe par ANext() (OnAfterControllerAction est alors sauté). Filtres prêts à l'emploi : AuthorizeEndpointFilter, RequireRoleEndpointFilter, BasicAuthEndpointFilter, CORSEndpointFilter, CSRFEndpointFilter, SessionEndpointFilter, MemorySessionEndpointFilter, FileSessionEndpointFilter, DatabaseSessionEndpointFilter, ActiveRecordEndpointFilter.
  • Bundles (IMVCFilterBundle, TMVCFilterBundle dans MVCFramework) : un ensemble avec une liste de filtres HTTP et une liste de filtres d'endpoint, enregistrés par un seul Use à l'endroit de l'appel ; sur un groupe Minimal API, la partie HTTP va sur l'engine et la partie d'endpoint sur le groupe. TMVCFilterBundle n'a pas de méthodes virtuelles : un bundle personnalisé est une fonction qui renvoie TMVCFilterBundle.Create([...], [...]). Use lève EMVCConfigException pour la même instance enregistrée deux fois ou sur l'engine et sur un groupe, et pour un bundle sans partie d'endpoint sur un groupe. JWTAuthenticationBundle : login POST /login avec jwtusername/jwtpassword qui répond {"token": ...} ; avec RefreshTokenStore dans les options, le login répond access_token et refresh_token, et la réutilisation d'un refresh token donne 401. CustomAuthenticationBundle doit être enregistré après un filtre HTTP de session.
  • Ordre : le premier filtre enregistré est le plus extérieur et les filtres enveloppent les middleware classiques quel que soit l'ordre par rapport à AddMiddleware ; ETagHTTPFilter avant CompressionHTTPFilter ; ActiveRecordHTTPFilter et sessions au point le plus intérieur, de sorte qu'une requête rejetée (429) ou servie comme fichier statique n'ouvre pas de connexion.
  • Différences pour qui migre : CORS démarre avec les credentials désactivés, les en-têtes Content-Type,Authorization, max-age 1728000 (le middleware : credentials actifs, autres en-têtes, max-age 60) ; ETag entre guillemets avec support de W/ (le middleware : digest sans guillemets) ; RedirectHTTPFilter compare le chemin sans tenir compte de la casse ; AnalyticsHTTPFilter écrit le PathInfo à la place de controller et action ; les filtres de session prennent un set TMVCSessionCookieFlags ([scfHttpOnly, scfSecure], par défaut [scfHttpOnly]) à la place des deux Boolean HttpOnly et Secure des anciens Use*SessionMiddleware, avec le helper SessionCookieFlags(ASecure) pour le construire à partir d'un Boolean ; RedirectHTTPFilter distingue 302 et 301 avec TMVCRedirectKind (rdkTemporary, par défaut, ou rdkPermanent) et conserve ou supprime la query string avec TMVCRedirectQuery (rdqPreserve, par défaut, ou rdqDrop) : dans les signatures des filtres, les Boolean qui ne s'expliquent pas tout seuls ont été remplacés par des types qui se lisent tout seuls (la boolean trap). Il en va de même pour TraceHTTPFilter (set TMVCTraceFlags : tfLogAuthorization, tfLogNonTextBody), SwaggerHTTPFilter (set TMVCSwaggerAuthentications : sauBasic, sauBearer, en cinquième position à la place des deux Boolean du middleware, donc un paramètre de moins) et les options des fichiers statiques (Mode : sfmFiles ou sfmSPA ; Flags : sffCaseSensitivePrefix). Restent des Boolean AAllowsCredentials de CORSHTTPFilter, qui reprend le paramètre du même nom du middleware CORS, et SessionCookieFlags(ASecure), qui convertit une valeur lue dans le fichier .env. StaticFilesHTTPFilter a le fallback pour les single page applications désactivé par défaut (dans le middleware il est actif) : on l'active avec StaticFilesHTTPFilter('/', folder, sfmSPA) ou avec Mode := sfmSPA dans les options (TMVCStaticFilesOptions) : le filtre laisse le routeur décider et répond index.html seulement à un GET ou HEAD pour lequel l'application n'a aucune route, il peut donc aussi se trouver sur / avec l'API à côté (il faut AllowUnhandledAction = false, la valeur par défaut, et le routeur écrit dans le log ROUTE NOT FOUND pour chaque route côté client) ; le troisième paramètre de la forme simple est le mode (TMVCStaticFilesMode), le document d'index est le quatrième ; les filtres n'écrivent pas la ligne de log pour chaque fichier servi qu'écrivait le middleware, et StaticFilesHTTPFilter sert .webp, .woff, .woff2 et .ttf avec le bon type. CompressionHTTPFilter ne recompresse pas une réponse qui a déjà un Content-Encoding. SecurityHeadersHTTPFilter, ShutdownHTTPFilter, OpenAPIHTTPFilter, RangeMediaHTTPFilter et TraceHTTPFilter ont les mêmes valeurs par défaut que les middleware (TraceHTTPFilter renvoie l'id de corrélation X-Request-ID, masque Authorization et enregistre le body jusqu'à 1024 octets ; la signature est TraceHTTPFilter(AMaxBodySize, ALogTag, AFlags, ACorrelationHeaderName), avec AFlags en plus en troisième position) ; ActiveRecordHTTPFilter active les connexions supplémentaires pour chaque instance (le middleware seulement pour la première du processus). RateLimitHTTPFilter avec options : mêmes options et même réponse que le middleware (429, Retry-After, body JSON).
  • Auteur : Daniele Teti, créateur de DelphiMVCFramework.

Comments