github.com/System-Glitch/goyave/v2@v2.10.3-0.20200819142921-51011e75d504/docs/guide/basics/middleware.html (about) 1 <!DOCTYPE html> 2 <html lang="en-US"> 3 <head> 4 <meta charset="utf-8"> 5 <meta name="viewport" content="width=device-width,initial-scale=1"> 6 <title>Middleware | Goyave</title> 7 <meta name="generator" content="VuePress 1.5.3"> 8 <link rel="icon" type="image/png" sizes="16x16" href="/goyave/goyave_16.png"> 9 <link rel="icon" type="image/png" sizes="32x32" href="/goyave/goyave_32.png"> 10 <link rel="icon" type="image/png" sizes="64x64" href="/goyave/goyave_64.png"> 11 <link rel="icon" type="image/png" sizes="128x128" href="/goyave/goyave_128.png"> 12 <link rel="icon" type="image/png" sizes="256x256" href="/goyave/goyave_256.png"> 13 <link rel="icon" type="image/png" sizes="512x512" href="/goyave/goyave_512.png"> 14 <meta name="description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 15 <meta name="og:title" content="Middleware - Goyave"> 16 <meta name="twitter:title" content="Middleware - Goyave"> 17 <meta name="title" content="Middleware - Goyave"> 18 <meta property="twitter:description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 19 <meta property="twitter:image:src" content="https://system-glitch.github.io/goyave/goyave_banner.png"> 20 <meta property="twitter:card" content="summary_large_image"> 21 <meta property="og:type" content="website"> 22 <meta property="og:description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 23 <meta property="og:image" content="https://system-glitch.github.io/goyave/goyave_banner.png"> 24 <meta property="og:site_name" content="Goyave"> 25 <link rel="preload" href="/goyave/assets/css/0.styles.589fd562.css" as="style"><link rel="preload" href="/goyave/assets/js/app.092490a7.js" as="script"><link rel="preload" href="/goyave/assets/js/4.75a9cc68.js" as="script"><link rel="preload" href="/goyave/assets/js/1.121dd9ed.js" as="script"><link rel="preload" href="/goyave/assets/js/19.90e0dab8.js" as="script"><link rel="preload" href="/goyave/assets/js/5.c83f1192.js" as="script"><link rel="prefetch" href="/goyave/assets/js/10.2f07bbf5.js"><link rel="prefetch" href="/goyave/assets/js/11.2d66fdef.js"><link rel="prefetch" href="/goyave/assets/js/12.63171b15.js"><link rel="prefetch" href="/goyave/assets/js/13.770050f3.js"><link rel="prefetch" href="/goyave/assets/js/14.b933d8cf.js"><link rel="prefetch" href="/goyave/assets/js/15.36df2a66.js"><link rel="prefetch" href="/goyave/assets/js/16.ed66719e.js"><link rel="prefetch" href="/goyave/assets/js/17.7bef5f05.js"><link rel="prefetch" href="/goyave/assets/js/18.470b55ed.js"><link rel="prefetch" href="/goyave/assets/js/20.3a300ca3.js"><link rel="prefetch" href="/goyave/assets/js/21.c3fd6053.js"><link rel="prefetch" href="/goyave/assets/js/22.d5569617.js"><link rel="prefetch" href="/goyave/assets/js/23.931b2034.js"><link rel="prefetch" href="/goyave/assets/js/24.1a4755e7.js"><link rel="prefetch" href="/goyave/assets/js/25.0d463913.js"><link rel="prefetch" href="/goyave/assets/js/26.3c173a7a.js"><link rel="prefetch" href="/goyave/assets/js/27.9c5b36f2.js"><link rel="prefetch" href="/goyave/assets/js/28.41e055b7.js"><link rel="prefetch" href="/goyave/assets/js/29.b87adf4a.js"><link rel="prefetch" href="/goyave/assets/js/3.ef71e77d.js"><link rel="prefetch" href="/goyave/assets/js/6.2336bf0c.js"><link rel="prefetch" href="/goyave/assets/js/7.d60e55c1.js"><link rel="prefetch" href="/goyave/assets/js/8.2ee33a42.js"><link rel="prefetch" href="/goyave/assets/js/9.8e043d60.js"> 26 <link rel="stylesheet" href="/goyave/assets/css/0.styles.589fd562.css"> 27 </head> 28 <body> 29 <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/goyave/" class="home-link router-link-active"><img src="/goyave/goyave_64.png" alt="Goyave" class="logo"> <span class="site-name can-hide">Goyave</span></a> <div class="links"><div class="user-settings"><a title="Dark theme" href="#" class="settings-button"><svg aria-hidden="true" data-prefix="fas" data-icon="cog" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="svg-inline--fa fa-cog fa-w-16 settings-icon"><path fill="currentColor" d="M8 0c-4.4 0-8 3.6-8 8s3.6 8 8 8 8-3.6 8-8-3.6-8-8-8zM8 15c-3.9 0-7-3.1-7-7 0-2.4 1.2-4.6 3.2-5.9-0.1 0.6-0.2 1.3-0.2 1.9 0 4.9 4 8.9 8.9 9-1.3 1.3-3 2-4.9 2z"></path></svg></a></div> <div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/goyave/guide/" class="nav-link router-link-active"> 30 Guide 31 </a></div><div class="nav-item"><a href="https://pkg.go.dev/github.com/System-Glitch/goyave/v2" target="_blank" rel="noopener noreferrer" class="nav-link external"> 32 pkg.go.dev 33 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <a href="https://github.com/System-Glitch/goyave" target="_blank" rel="noopener noreferrer" class="repo-link"> 34 GitHub 35 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/goyave/guide/" class="nav-link router-link-active"> 36 Guide 37 </a></div><div class="nav-item"><a href="https://pkg.go.dev/github.com/System-Glitch/goyave/v2" target="_blank" rel="noopener noreferrer" class="nav-link external"> 38 pkg.go.dev 39 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <a href="https://github.com/System-Glitch/goyave" target="_blank" rel="noopener noreferrer" class="repo-link"> 40 GitHub 41 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></nav> <ul class="sidebar-links"><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading"><span>Guide</span> <span class="arrow right"></span></p> <!----></section></li><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading open"><span>The Basics</span> <span class="arrow down"></span></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/goyave/guide/basics/routing.html" class="sidebar-link">Routing</a></li><li><a href="/goyave/guide/basics/middleware.html" aria-current="page" class="active sidebar-link">Middleware</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/goyave/guide/basics/middleware.html#introduction" class="sidebar-link">Introduction</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/basics/middleware.html#writing-middleware" class="sidebar-link">Writing middleware</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/basics/middleware.html#applying-middleware" class="sidebar-link">Applying Middleware</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/basics/middleware.html#built-in-middleware" class="sidebar-link">Built-in middleware</a></li></ul></li><li><a href="/goyave/guide/basics/requests.html" class="sidebar-link">Requests</a></li><li><a href="/goyave/guide/basics/controllers.html" class="sidebar-link">Controllers</a></li><li><a href="/goyave/guide/basics/responses.html" class="sidebar-link">Responses</a></li><li><a href="/goyave/guide/basics/database.html" class="sidebar-link">Database</a></li><li><a href="/goyave/guide/basics/validation.html" class="sidebar-link">Validation</a></li></ul></section></li><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading"><span>Advanced</span> <span class="arrow right"></span></p> <!----></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="middleware"><a href="#middleware" class="header-anchor">#</a> Middleware</h1> <p></p><div class="table-of-contents"><ul><li><a href="#introduction">Introduction</a></li><li><a href="#writing-middleware">Writing middleware</a></li><li><a href="#applying-middleware">Applying Middleware</a></li><li><a href="#built-in-middleware">Built-in middleware</a><ul><li><a href="#disallownonvalidatedfields">DisallowNonValidatedFields</a></li><li><a href="#trim">Trim</a></li><li><a href="#gzip">Gzip</a></li></ul></li></ul></div><p></p> <h2 id="introduction"><a href="#introduction" class="header-anchor">#</a> Introduction</h2> <p>Middleware are handlers executed before the controller handler. They are a convenient way to filter, intercept or alter HTTP requests entering your application. For example, middleware can be used to authenticate users. If the user is not authenticated, a message is sent to the user even before the controller handler is reached. However, if the user is authenticated, the middleware will pass to the next handler. Middleware can also be used to sanitize user inputs, by trimming strings for example, to log all requests into a log file, to automatically add headers to all your responses, etc.</p> <p>Writing middleware is as easy as writing standard handlers. In fact, middleware are handlers, but they have an additional responsibility: when they are done, the may or may not pass to the next handler, which is either another middleware or a controller handler.</p> <h2 id="writing-middleware"><a href="#writing-middleware" class="header-anchor">#</a> Writing middleware</h2> <p>Each middleware is written in its own file inside the <code>http/middleware</code> directory. A <code>Middleware</code> is a function returning a <code>Handler</code>.</p> <div class="custom-block tip"><p class="custom-block-title">TIP</p> <p><code>goyave.Middleware</code> is an alias for <code>func(goyave.Handler) goyave.Handler</code></p></div> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">func</span> <span class="token function">MyCustomMiddleware</span><span class="token punctuation">(</span>next goyave<span class="token punctuation">.</span>Handler<span class="token punctuation">)</span> goyave<span class="token punctuation">.</span>Handler <span class="token punctuation">{</span> 42 <span class="token keyword">return</span> <span class="token keyword">func</span><span class="token punctuation">(</span>response <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Response<span class="token punctuation">,</span> request <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Request<span class="token punctuation">)</span> <span class="token punctuation">{</span> 43 <span class="token comment">// Do something</span> 44 <span class="token function">next</span><span class="token punctuation">(</span>response<span class="token punctuation">,</span> request<span class="token punctuation">)</span> <span class="token comment">// Pass to the next handler</span> 45 <span class="token punctuation">}</span> 46 <span class="token punctuation">}</span> 47 </code></pre></div><p>When implementing middleware, keep in mind that the request <strong>has not been validated yet</strong>! Manipulating unvalidated data can be dangerous, especially in form-data where the data types are not converted by the validator yet. In middleware, you should always check if the request has been parsed correctly before trying to access its data:</p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">if</span> request<span class="token punctuation">.</span>Data <span class="token operator">!=</span> <span class="token boolean">nil</span> <span class="token punctuation">{</span> 48 <span class="token comment">// Parsing OK</span> 49 <span class="token punctuation">}</span> 50 </code></pre></div><p>If you want your middleware to stop the request and respond immediately before reaching the controller handler, simply don't call the <code>next</code> handler. In the following example, consider that you developed a custom authentication system:</p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">func</span> <span class="token function">CustomAuthentication</span><span class="token punctuation">(</span>next goyave<span class="token punctuation">.</span>Handler<span class="token punctuation">)</span> goyave<span class="token punctuation">.</span>Handler <span class="token punctuation">{</span> 51 <span class="token keyword">return</span> <span class="token keyword">func</span><span class="token punctuation">(</span>response <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Response<span class="token punctuation">,</span> request <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Request<span class="token punctuation">)</span> <span class="token punctuation">{</span> 52 <span class="token keyword">if</span> <span class="token operator">!</span>auth<span class="token punctuation">.</span><span class="token function">Check</span><span class="token punctuation">(</span>request<span class="token punctuation">)</span> <span class="token punctuation">{</span> 53 response<span class="token punctuation">.</span><span class="token function">Status</span><span class="token punctuation">(</span>http<span class="token punctuation">.</span>StatusUnauthorized<span class="token punctuation">)</span> 54 <span class="token keyword">return</span> 55 <span class="token punctuation">}</span> 56 57 <span class="token function">next</span><span class="token punctuation">(</span>response<span class="token punctuation">,</span> request<span class="token punctuation">)</span> 58 <span class="token punctuation">}</span> 59 <span class="token punctuation">}</span> 60 </code></pre></div><div class="custom-block tip"><p class="custom-block-title">TIP</p> <p>When a middleware stops a request, following middleware are <strong>not</strong> executed neither.</p></div> <h2 id="applying-middleware"><a href="#applying-middleware" class="header-anchor">#</a> Applying Middleware</h2> <p>When your middleware is ready, you will need to apply it to a router or a specific route. When applying a middleware to a router, all routes and subrouters will execute this middleware when matched.</p> <div class="language-go extra-class"><pre class="language-go"><code>router<span class="token punctuation">.</span><span class="token function">Middleware</span><span class="token punctuation">(</span>middleware<span class="token punctuation">.</span>MyCustomMiddleware<span class="token punctuation">)</span> 61 62 router<span class="token punctuation">.</span><span class="token function">Get</span><span class="token punctuation">(</span><span class="token string">"/products"</span><span class="token punctuation">,</span> product<span class="token punctuation">.</span>Index<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">Middleware</span><span class="token punctuation">(</span>middleware<span class="token punctuation">.</span>MyCustomMiddleware<span class="token punctuation">)</span> 63 </code></pre></div><h2 id="built-in-middleware"><a href="#built-in-middleware" class="header-anchor">#</a> Built-in middleware</h2> <p>Built-in middleware is located in the <code>middleware</code> package.</p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">import</span> <span class="token string">"github.com/System-Glitch/goyave/v2/middleware"</span> 64 </code></pre></div><h3 id="disallownonvalidatedfields"><a href="#disallownonvalidatedfields" class="header-anchor">#</a> DisallowNonValidatedFields</h3> <p>DisallowNonValidatedFields validates that all fields in the request are validated by the RuleSet. The middleware stops the request and sends "422 Unprocessable Entity" and an error message if the user has sent non-validated field(s). Fields ending with <code>_confirmation</code> are ignored.</p> <p>If the body parsing failed, this middleware immediately passes to the next handler. <strong>This middleware shall only be used with requests having a rule set defined.</strong></p> <p>The returned error message can be customized using the entry <code>disallow-non-validated-fields</code> in the <code>locale.json</code> language file.</p> <div class="language-go extra-class"><pre class="language-go"><code>router<span class="token punctuation">.</span><span class="token function">Middleware</span><span class="token punctuation">(</span>middleware<span class="token punctuation">.</span>DisallowNonValidatedFields<span class="token punctuation">)</span> 65 </code></pre></div><h3 id="trim"><a href="#trim" class="header-anchor">#</a> Trim</h3> <p><span class="badge tip" style="vertical-align:top;" data-v-15b7b770>Since v2.0.0</span></p> <p>Trim removes all leading and trailing white space from string fields.</p> <p>For example, <code>" \t trimmed\n \t"</code> will be transformed to <code>"trimmed"</code>.</p> <div class="language-go extra-class"><pre class="language-go"><code>router<span class="token punctuation">.</span><span class="token function">Middleware</span><span class="token punctuation">(</span>middleware<span class="token punctuation">.</span>Trim<span class="token punctuation">)</span> 66 </code></pre></div><h3 id="gzip"><a href="#gzip" class="header-anchor">#</a> Gzip</h3> <p><span class="badge tip" style="vertical-align:top;" data-v-15b7b770>Since v2.7.0</span></p> <p>Gzip compresses HTTP responses with default compression level for clients that support it via the <code>Accept-Encoding</code> header.</p> <div class="language-go extra-class"><pre class="language-go"><code>router<span class="token punctuation">.</span><span class="token function">Middleware</span><span class="token punctuation">(</span>middleware<span class="token punctuation">.</span><span class="token function">Gzip</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span> 67 </code></pre></div><p>The compression level can be specified using <code>GzipLevel(level)</code>. The compression level should be <code>gzip.DefaultCompression</code>, <code>gzip.NoCompression</code>, or any integer value between <code>gzip.BestSpeed</code> and <code>gzip.BestCompression</code> inclusive. <code>gzip.HuffmanOnly</code> is also available.</p> <div class="language-go extra-class"><pre class="language-go"><code>router<span class="token punctuation">.</span><span class="token function">Middleware</span><span class="token punctuation">(</span>middleware<span class="token punctuation">.</span><span class="token function">GzipLevel</span><span class="token punctuation">(</span>gzip<span class="token punctuation">.</span>BestCompression<span class="token punctuation">)</span><span class="token punctuation">)</span> 68 </code></pre></div></div> <footer class="page-edit"><div class="edit-link"><a href="https://github.com/System-Glitch/goyave/edit/master/docs_src/src/guide/basics/middleware.md" target="_blank" rel="noopener noreferrer">Edit this page on GitHub</a> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></div> <!----></footer> <div class="page-nav"><p class="inner"><span class="prev"> 69 ← 70 <a href="/goyave/guide/basics/routing.html" class="prev"> 71 Routing 72 </a></span> <span class="next"><a href="/goyave/guide/basics/requests.html"> 73 Requests 74 </a> 75 → 76 </span></p></div> </main></div><div class="global-ui"><!----></div></div> 77 <script src="/goyave/assets/js/app.092490a7.js" defer></script><script src="/goyave/assets/js/4.75a9cc68.js" defer></script><script src="/goyave/assets/js/1.121dd9ed.js" defer></script><script src="/goyave/assets/js/19.90e0dab8.js" defer></script><script src="/goyave/assets/js/5.c83f1192.js" defer></script> 78 </body> 79 </html>