📌Getting started
🔌Routing
🗜️Compression
🖼️ View/Templates
📁File Server
🌎Localization
🛡️Security
🚀Responses
📥
Requests
💉Dependency Injection
Middleware
When we refer to the concept of Middleware within Iris, we're talking about running code before or after our main handler within an HTTP request's lifecycle. For example, a middleware called "logger" might write incoming request details to a file or the console, before proceeding with the main handler. One of the cool things about middleware is that these units are incredibly flexible and reusable within and across your applications!
A middleware is just an iris.Handler taking the form of
func(ctx iris.Context). Each middleware is executed when the previous middleware calls the ctx.Next() method, which can be used for authentication, i.e., if the request isn't authorized to continue, we could throw an error response instead of calling this method.Iris has 7 (+1) different ways to register middleware, depending on your application's requirements. Party.UseError, Party.Use, Party.UseOnce, Application.UseGlobal, Party.Done, Application.DoneGlobal, Party.UseRouter and Application.WrapRouter. Iris gives you the tools to have full control over the request flow.
Register A Middleware
Let's dive into the details of each one of the above methods through a quick lesson on how you can register middlewares in an Iris Application and Party (group of routes). Below you will see a simple example which outputs to the client the order of execution of each registered handler.
1
package main
2
3
import (
4
"net/http"
5
6
"github.com/kataras/iris/v12"
7
)
8
9
func main() {
10
app := iris.New()
11
12
app.WrapRouter(routerWrapper)
13
app.UseRouter(routerMiddleware)
14
app.UseGlobal(globalMiddleware)
15
app.Use(useMiddleware)
16
app.UseError(errorMiddleware)
17
// app.Done(done)
18
// app.DoneGlobal(doneGlobal)
19
20
// Adding a OnErrorCode(iris.StatusNotFound) causes `.UseGlobal`
21
// to be fired on 404 pages without this,
22
// only `UseError` will be called, and thus should
23
// be used for error pages.
24
app.OnErrorCode(iris.StatusNotFound, notFoundHandler)
25
26
app.Get("/", mainHandler)
27
28
app.Listen(":8080")
29
}
30
31
func mainHandler(ctx iris.Context) {
32
ctx.WriteString("Main Handler")
33
}
34
35
func notFoundHandler(ctx iris.Context) {
36
ctx.WriteString("404 Error Handler")
37
}
Copied!
The Application.WrapRouter Method
Application.WrapRouter MethodA WrapperFunc registered in this way runs for the whole Application, before anything else. It is executed last registered first, unlike other middleware methods. A
WrapperFunc is not an iris.Handler, instead its signature is: func(http.ResponseWriter, *http.Request, router http.HandlerFunc). It's the lowest-level functionality used to intercept requests and optionally change the behaviour of the router (e.g. navigate to another route than the requested path one, perform security checks before even the router is executed and more). A good example of use-case is a CORS implementation.The Party.UseRouter Method
Party.UseRouter MethodA middleware registered in this way will run under a specific Party's path prefix on all routes (whether they are matched or not, including routes that would result in an error.) All child Parties inherit them unless
Party.ResetRouteFilters() or Party.Reset() is called. They are executed in the order they are registered, and they run before UseGlobal and Use on matched routes or UseError on errors.The Application.UseGlobal Method
Application.UseGlobal MethodA middleware registered in this way will run on all previous and future routes, and registered error handlers (pages matched with
OnErrorCode), in the whole Application (all Parties and Subdomains included.) They are also executed in the order they are registered, and they run before Use or UseError.The Party.Use Method
Party.Use MethodA middleware registered in this way will run after
UseGlobal under a particular Party and its children. They are also executed in the order they are registered, and they run right before the Handle itself (such as Get, Post, Patch, ...) It is not executed on errors.The Party.UseError Method
Party.UseError MethodA middleware registered in this way will run only when an HTTP error is encountered (such as the case with an unavailable
404 or protected 401 resources), unlike Use. They fire for all children Parties and will be called in the order they were registered.The Party.Done Method
Party.Done MethodRegister handler to run after routes middleware and handlers under a specific Party and its children. Requires a
ctx.Next call on the last route's handler, unless Execution Rules are modified.The Application.DoneGlobal Method
Application.DoneGlobal MethodSame as
UseGlobal but for the Done handlers. Runs on the Application instance level, after everything else.The middlewares used for this example are included below:
1
func routerWrapper(w http.ResponseWriter, r *http.Request,
2
router http.HandlerFunc) {
3
4
if r.URL.Path == "/" {
5
w.Write([]byte("#1 .WrapRouter\n"))
6
/* Note for new Gophers:
7
If we Write anything here on an error resource in the raw
8
`net/http` wrapper like this one, then the response writer will
9
automatically send a `200` OK status code (when we first write).
10
Any error handler executed after this will not fire as expected.
11
Also, when `w.WriteHeader` is called you can NOT change the
12
status code later on.
13
14
In Iris Handlers, if you write before the status code has been
15
set, then it will also automatically send the 200 OK status
16
code which then cannot be changed later. However, if we call
17
`ctx.StatusCode` inside an Iris Handler without writing any
18
content, then we can change the status code later on. When you
19
need to change that behaviour, you must start the handler with
20
a `ctx.Record` call.
21
*/
22
}
23
24
// Continue by executing the Iris Router and let it do its job.
25
router(w, r)
26
}
27
28
29
func routerMiddleware(ctx iris.Context) {
30
if ctx.Path() == "/" {
31
ctx.WriteString("#2 .UseRouter\n")
32
// The same caveat described in routerWrapper applies here as well.
33
}
34
35
ctx.Next()
36
}
37
38
func globalMiddleware(ctx iris.Context) {
39
ctx.WriteString("#3 .UseGlobal\n")
40
ctx.Next()
41
}
42
43
func useMiddleware(ctx iris.Context) {
44
ctx.WriteString("#4 .Use\n")
45
ctx.Next()
46
}
47
48
func errorMiddleware(ctx iris.Context) {
49
ctx.WriteString("#3 .UseError\n")
50
ctx.Next()
51
}
Copied!
Run our simple application:
1
$ go run main.go
2
Now listening on: http://localhost:8080
3
Application started. Press CTRL+C to shut down.
Copied!
Point your browser to
http://localhost:8080, and the output should look exactly like this:1
#1 .WrapRouter
2
#2 .UseRouter
3
#3 .UseGlobal
4
#4 .Use
5
Main Handler
Copied!
And for a page that should give a 404, such as
http://localhost:8080/a_not_found_resource:1
#3 .UseGlobal
2
#3 .UseError
3
404 Error Handler
Copied!
(Note that
WrapRouter and UseRouter are still fired 1st and 2nd, just not shown in the output. Read the block comment to learn why.)However, without an
OnErrorCode:It is important to note that without
OnErrorCode registered, your UseGlobal will not be executed.1
#3 .UseError
2
Not Found
Copied!
Modify A Middleware
You can modify the behavior of any existing middleware by wrapping it.
Let's take, for example, that you want to register a middleware on
UseRouter to run everywhere except on the static.example.com subdomain.You have two ways to do that. The first one is:
1
package main
2
3
import (
4
"github.com/kataras/iris/v12"
5
"github.com/kataras/iris/v12/middleware/basicauth"
6
)
7
8
func main() {
9
users := map[string]string{"username":"password"}
10
auth := basicauth.Default(users)
11
12
app.UseRouter(skipStaticSubdomain(auth)) // <--
13
14
// [...]
15
app.Listen(":80")
16
}
17
18
func skipStaticSubdomain(handler iris.Handler) iris.Handler {
19
return func(ctx iris.Context) {
20
if ctx.Subdomain() == "static." {
21
// continue to the next or main handler and exit.
22
ctx.Next()
23
return
24
}
25
26
handler(ctx)
27
}
28
}
Copied!
1
type Filter func(Context) bool
2
3
func NewConditionalHandler(filter Filter, handlers ...Handler) Handler
Copied!
Here is a usage example, which checks if a subdomain exists and it is NOT the
static. one:1
app.UseRouter(iris.NewConditionalHandler(isNotStaticSubdomain, auth))
Copied!
1
func isNotStaticSubdomain(ctx iris.Context) bool {
2
return ctx.Subdomain() != "static."
3
}
Copied!
That's all. When you've got the idea, it's trivial.
Transfer Data Between Handlers
Each request-response lifecycle contains an instance of
iris.Context. This instance is shared across the handlers chain—the Context.Values() returns temporary memory storage which can be used to transfer data between middleware and handlers.This storage contains many helper methods, the most important you'll probably use are:
1
Set(key string, value interface{}) (Entry, bool)
2
Get(key string) interface{}
Copied!
Usage
Set a value:
1
func myMiddleware(ctx iris.Context) {
2
ctx.Values().Set("key", value)
3
}
Copied!
Get a value:
1
func myHandler(ctx iris.Context) {
2
value := ctx.Values().Get("key")
3
}
Copied!
Writing a middleware
1
package main
2
3
import "github.com/kataras/iris/v12"
4
5
func main() {
6
app := iris.New()
7
// or app.Use(before) and app.Done(after).
8
app.Get("/", before, mainHandler, after)
9
app.Listen(":8080")
10
}
11
12
func before(ctx iris.Context) {
13
shareInformation := "this is a sharable information between handlers"
14
15
requestPath := ctx.Path()
16
println("Before the mainHandler: " + requestPath)
17
18
ctx.Values().Set("info", shareInformation)
19
ctx.Next() // execute the next handler, in this case the main one.
20
}
21
22
func after(ctx iris.Context) {
23
println("After the mainHandler")
24
}
25
26
func mainHandler(ctx iris.Context) {
27
println("Inside mainHandler")
28
29
// take the info from the "before" handler.
30
info := ctx.Values().GetString("info")
31
32
// write something to the client as a response.
33
ctx.HTML("<h1>Response</h1>")
34
ctx.HTML("<br/> Info: " + info)
35
36
ctx.Next() // execute the "after".
37
}
Copied!
1
$ go run main.go # and navigate to the http://localhost:8080
2
Now listening on: http://localhost:8080
3
Application started. Press CTRL+C to shut down.
4
Before the mainHandler: /
5
Inside mainHandler
6
After the mainHandler
Copied!
Removing a Handler from a Route
To remove a specific handler from a specific route use the
RemoveHandler method of the *Route registered by the Handle/Get/Post/Put... methods. The RemoveHandler method expects the handler name (it's the PC func, see HandlerName of the iris context subpackage) or the handler itself.Example Code:
1
func middleware(ctx iris.Context) {
2
// [...]
3
}
4
5
func main() {
6
app := iris.New()
7
8
// Register the middleware to all matched routes.
9
app.Use(middleware)
10
11
// Handlers = middleware, other
12
app.Get("/", index)
13
14
// Handlers = other
15
app.Get("/other", other).RemoveHandler(middleware)
16
}
Copied!
Execution Rules
You could also use the
ExecutionRules to force Begin(UseXXX) and Finish(DoneXXX) handlers to be executed without the requirement of a ctx.Next() call, to forcibly forward them:1
app.SetExecutionRules(iris.ExecutionRules{
2
// Begin: ...
3
// Main: ...
4
Done: iris.ExecutionOptions{Force: true},
5
})
Copied!
Convert http.Handler/HandlerFunc
http.Handler/HandlerFuncHowever, you are not limited to them - you are free to use any third-party middleware that is compatible with the net/http package.
Iris, unlike others, is 100% compatible with the standards and that's why the majority of big companies that adapt Go to their workflow, like a very famous US Television Network, trust Iris; it's up-to-date, and it will always be aligned with the std
net/http package which is modernized by the Go Authors on each new release of the Go Programming Language.Any third-party middleware that written for
net/http is compatible with Iris using the iris.FromStd(aThirdPartyMiddleware). Remember, ctx.ResponseWriter() and ctx.Request() returns the same net/http input arguments of an http.Handler.Here is a list of some handlers made specifically for Iris:
Built-in
Middleware
Example
Community
Middleware
Description
Example
An authorization library that supports access control models like ACL, RBAC, ABAC
Middleware checks for a JWT on the
Authorization header on incoming requests and decodes it
Middleware that implements a few quick security wins
Generic middleware to rate-limit HTTP requests
Third-Party
Iris has its own middleware form of
func(ctx iris.Context), but it's also compatible with all net/http middleware forms. See here.Here's a small list of useful third-party handlers:
Middleware
Description
Add delays/latency to endpoints. Useful when testing effects of high latency
Generate TinySVG, HTML and CSS on the fly
Secure authentication for REST API endpoints
Store information about your web application (response time, etc.)
Last modified 11mo ago
Export as PDF
Copy link
Contents
Register A Middleware
The Application.WrapRouter Method
The Party.UseRouter Method
The Application.UseGlobal Method
The Party.Use Method
The Party.UseError Method
The Party.Done Method
The Application.DoneGlobal Method
Modify A Middleware
Transfer Data Between Handlers
Usage
Writing a middleware
Removing a Handler from a Route
Execution Rules
Convert http.Handler/HandlerFunc
Built-in
Community
Third-Party