DelphiMVCFramework 3.5.0-silicon : des middleware aux filtres, qu'arrive-t-il à ton serveur ?
🇮🇹 Italiano • 🇬🇧 English • 🇪🇸 Español • 🇩🇪 Deutsch • 🇧🇷 Português

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 :

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 classique | Filtre HTTP | |
|---|---|---|
| Interface | IMVCMiddleware, quatre méthodes | une procédure avec AContext et ANext |
| S’enregistre avec | AEngine.AddMiddleware(...) | AEngine.Use(...) |
| Quand il s’exécute | aux quatre points du cycle, dans l’ordre d’enregistrement | autour de toute la requête : middleware classiques, routing et action |
| Avant et après | deux méthodes séparées | même procédure : avant et après ANext() |
| Pour arrêter la requête | Handled := True | tu n’appelles pas ANext() |
| Controller | oui | oui |
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 ?
OnBeforeRoutingdevient le code avantANext().OnAfterRoutingdevient le code aprèsANext(). 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 deANext()et répond 500, et le code aprèsANext()s’exécute quand même, commeOnAfterRouting. Untry..finallyautour deANext()est utile pour les exceptions qui viennent d’un filtre HTTP plus intérieur.OnBeforeControllerActionetOnAfterControllerActionn’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 :

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 :

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é | Filtre | Comment l’enregistrer |
|---|---|---|
TMVCRedirectMiddleware | RedirectHTTPFilter | Use(RedirectHTTPFilter(['/'], '/web')) |
TMVCStaticFilesMiddleware | StaticFilesHTTPFilter | Use(StaticFilesHTTPFilter('/static', lWwwPath)) |
TMVCAnalyticsMiddleware | AnalyticsHTTPFilter | Use(AnalyticsHTTPFilter()) |
TMVCTraceMiddleware | TraceHTTPFilter | Use(TraceHTTPFilter()) |
TMVCCompressionMiddleware | CompressionHTTPFilter | Use(CompressionHTTPFilter(1024)) |
TMVCETagMiddleware | ETagHTTPFilter | Use(ETagHTTPFilter()) |
TMVCCORSMiddleware | CORSHTTPFilter | Use(CORSHTTPFilter('*')) |
TMVCSecurityHeadersMiddleware | SecurityHeadersHTTPFilter | Use(SecurityHeadersHTTPFilter()) |
TMVCShutdownMiddleware | ShutdownHTTPFilter | Use(ShutdownHTTPFilter('apikey', 'a-strong-secret')) |
TMVCRangeMediaMiddleware | RangeMediaHTTPFilter | Use(RangeMediaHTTPFilter('/static/media', 'static/media')) |
TMVCSwaggerMiddleware | SwaggerHTTPFilter | Use(SwaggerHTTPFilter(AEngine, lSwaggerInfo, '/openapi.json')) |
TMVCOpenAPI3Middleware | OpenAPIHTTPFilter | Use(OpenAPIHTTPFilter(AEngine, lOpenAPIInfo, '/openapi.json')) |
TMVCRateLimitMiddleware | RateLimitHTTPFilter | Use(RateLimitHTTPFilter(lRateLimitOptions)) |
TMVCActiveRecordMiddleware | ActiveRecordHTTPFilter | Use(ActiveRecordHTTPFilter('conn_def_name', 'FDConnectionDefs.ini')) |
UseMemorySessionMiddleware | MemorySessionHTTPFilter | Use(MemorySessionHTTPFilter(10, [scfHttpOnly, scfSecure])) |
UseFileSessionMiddleware | FileSessionHTTPFilter | Use(FileSessionHTTPFilter(10, 'sessions', [scfHttpOnly, scfSecure])) |
UseDatabaseSessionMiddleware | DatabaseSessionHTTPFilter | Use(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.Sessions’utilise comme toujours.DatabaseSessionHTTPFilterdoit être enregistré aprèsActiveRecordHTTPFilter. ActiveRecordHTTPFilterprend la connexion avant le dispatch et la libère quandANext()revient. Les connexions supplémentaires s’appliquent à chaque instance du filtre : le middleware ne les activait que pour la première du processus.RateLimitHTTPFilteravecTMVCRateLimitOptionsa 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êtesX-RateLimit-*, un callback quand une requête est rejetée. La réponse est 429 avecRetry-Afteret 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 :

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 :

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
TMVCCORSMiddleware | CORSHTTPFilter | |
|---|---|---|
| Credentials | activés | désactivés |
| En-têtes autorisés | Content-Type, Accept, jwtusername, jwtpassword, authentication, authorization | Content-Type,Authorization |
| Méthodes | POST,GET,OPTIONS,PUT,DELETE,PATCH | GET,POST,PUT,DELETE,PATCH,OPTIONS |
| Max-age | 60 secondes | 1728000 secondes |
Si un client dépend des anciennes valeurs, tu les passes comme paramètres :

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](/images/dmvcframework-middleware-to-http-filters/file-session-before-after.png)
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 :
RedirectHTTPFilterdistingue 302 et 301 avecTMVCRedirectKind(rdkTemporary,rdkPermanent) et conserve ou supprime la query string avecTMVCRedirectQuery(rdqPreserve,rdqDrop) ;TraceHTTPFilterprend le setTMVCTraceFlags(tfLogAuthorization,tfLogNonTextBody) ;SwaggerHTTPFilterprend le setTMVCSwaggerAuthentications(sauBasic,sauBearer) ;- les options de
StaticFilesHTTPFilterontMode(sfmFiles,sfmSPA) etFlags(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 :

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 :

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 :

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
OnBeforeControllerActiondes middleware classiques, et leur partie aprèsANext()se termine avant tous lesOnAfterControllerAction, quel que soit l’ordre d’enregistrement ; - une route Minimal API ne passe ni par
OnBeforeControllerActionni parOnAfterControllerAction, parce que la Minimal API s’exécute dans l’OnBeforeRoutingde son propre middleware, alors que le filtre d’endpoint s’exécute dans les deux cas ; ANext()renvoienilpour l’action d’un controller, qui a déjà écrit la réponse, et l’IMVCResponsedu 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 :

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 :

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ù | Comment | Pour quelles requêtes |
|---|---|---|
| Engine | AEngine.Use(filter) | chaque action des controllers et chaque route Minimal API |
| Groupe Minimal API | lGroup := lGroup.Use(filter) | les routes mappées ensuite sur le groupe et sur les groupes imbriqués |
| Une route | lGroup.MapGet(...).Use(filter) | cette route uniquement |

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 controller | Route Minimal API | |
|---|---|---|
AContext.ControllerQualifiedClassName | PipelineOrder.TOrderController | vide |
AContext.ActionName | Hello | GET /min/hello/($id) |
AContext.Request.Params['id'] | 42 | 42 |
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
| Filtre | Ce 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, DatabaseSessionEndpointFilter | sessions |
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 :

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
| Bundle | Partie HTTP | Partie d’endpoint | Middleware qu’il remplace |
|---|---|---|---|
JWTAuthenticationBundle | login ; blacklist et refresh token, si tu les configures | contrôle du token dans Authorization: Bearer | TMVCJWTAuthenticationMiddleware, TMVCJWTBlackListMiddleware, TMVCJWTRefreshTokenMiddleware |
JWTCookieAuthenticationBundle | login et logout, avec le contrôle de l’Origin du login (LoginAllowedOrigins) | contrôle du token dans le cookie | TMVCJWTCookieAuthenticationMiddleware |
BasicAuthenticationBundle | aucune | BasicAuthEndpointFilter | TMVCBasicAuthenticationMiddleware |
CustomAuthenticationBundle | login et logout sur /system/users/logged | contrôle de la session | TMVCCustomAuthenticationMiddleware, TMVCRoleBasedAuthMiddleware (avec TRoleBasedAuthHandler) |
OIDCAuthenticationBundle | login, callback et logout | session valide, sinon 302 vers le login | TMVCOIDCAuthenticationMiddleware |
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 :

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.

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 :

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 :

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
- Le guide officiel, deuxième édition - middleware et filtres HTTP au chapitre 14, filtres d’endpoint et Minimal API au chapitre 29, sur Leanpub
- DelphiMVCFramework 3.5 RC7 entre dans le Project Manager de Delphi et parle aux agents IA - le wizard, le menu du Project Manager, OpenAPI 3
- Delphi Minimal API - les routes avec des méthodes anonymes, sans classes controller
- Dépôt GitHub - code source et samples, aussi pour ouvrir une issue
– 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