# README
Iris Web Framework 
Iris is a fast, simple yet fully featured and very efficient web framework for Go.
It provides a beautifully expressive and easy to use foundation for your next website or API.
Learn what others saying about Iris and star this open-source project to support its potentials.
package main
import "github.com/kataras/iris/v12"
func main() {
app := iris.New()
app.Use(iris.Compression)
app.Get("/", func(ctx iris.Context) {
ctx.HTML("Hello <strong>%s</strong>!", "World")
})
app.Listen(":8080")
}
As one Go developer once said, Iris got you covered all-round and standing strong over the years.
Some of the features Iris offers:
- HTTP/2 (Push, even Embedded data)
- Middleware (Accesslog, Basicauth, CORS, gRPC, Anti-Bot hCaptcha, JWT, MethodOverride, ModRevision, Monitor, PPROF, Ratelimit, Anti-Bot reCaptcha, Recovery, RequestID, Rewrite)
- API Versioning
- Model-View-Controller
- Websockets
- gRPC
- Auto-HTTPS
- Builtin support for ngrok to put your app on the internet, the fastest way
- Unique Router with dynamic path as parameter with standard types like :uuid, :string, :int... and the ability to create your own
- Compression
- View Engines (HTML, Django, Handlebars, Pug/Jade and more)
- Create your own File Server and host your own WebDAV server
- Cache
- Localization (i18n, sitemap)
- Sessions
- Rich Responses (HTML, Text, Markdown, XML, YAML, Binary, JSON, JSONP, Protocol Buffers, MessagePack, Content Negotiation, Streaming, Server-Sent Events and more)
- Response Compression (gzip, deflate, brotli, snappy, s2)
- Rich Requests (Bind URL Query, Headers, Form, Text, XML, YAML, Binary, JSON, Validation, Protocol Buffers, MessagePack and more)
- Dependency Injection (MVC, Handlers, API Routers)
- Testing Suite
- And the most important... you get fast answers and support from the 1st day until now - that's six full years!
👑 Supporters
With your help, we can improve Open Source web development for everyone!
📖 Learning Iris
Installation
The only requirement is the Go Programming Language.
Create a new project
$ mkdir myapp
$ cd myapp
$ go mod init myapp
$ go get github.com/kataras/iris/v12@latest # or @v12.2.11
Install on existing project
$ cd myapp
$ go get github.com/kataras/iris/v12@latest
Run
$ go mod tidy -compat=1.22 # -compat="1.22" for windows.
$ go run .
Iris contains extensive and thorough documentation making it easy to get started with the framework.
For a more detailed technical documentation you can head over to our godocs. And for executable code you can always visit the ./_examples repository's subdirectory.
Do you like to read while traveling?
You can request a PDF and online access of the Iris E-Book (New Edition, future v12.2.0+) today and be participated in the development of Iris.
🙌 Contributing
We'd love to see your contribution to the Iris Web Framework! For more information about contributing to the Iris project please check the CONTRIBUTING.md file.
🛡 Security Vulnerabilities
If you discover a security vulnerability within Iris, please send an e-mail to [email protected]. All security vulnerabilities will be promptly addressed.
📝 License
This project is licensed under the BSD 3-clause license, just like the Go project itself.
The project name "Iris" was inspired by the Greek mythology.
# Functions
Addr can be used as an argument for the `Run` method.
AutoTLS can be used as an argument for the `Run` method.
Component returns a new Handler which can be registered as a main handler for a route.
Compression is a middleware which enables writing and reading using the best offered compression.
ConfigureMiddleware is a PartyConfigurator which can be used as a shortcut to add middlewares on Party.PartyConfigure("/path", WithMiddleware(handler), new(example.API)).
Default returns a new Application.
DefaultConfiguration returns the default configuration for an iris station, fills the main Configuration.
Listener can be used as an argument for the `Run` method.
Minify is a middleware which minifies the responses based on the response content type.
New creates and returns a fresh empty iris *Application instance.
NewContextPool returns a new ContextPool default implementation which uses sync.Pool to implement its Acquire and Release methods.
NewContextWrapper returns a new ContextWrapper.
NewGuide returns a simple Iris API builder.
NonBlocking sets the `Configuration.NonBlocking` field to true.
Patches returns the singleton of GlobalPatches, an easy way to modify global(package-level) configuration for Iris applications.
PrefixDir returns a new FileSystem that opens files by adding the given "prefix" to the directory tree of "fs".
PrefixFS same as "PrefixDir" but for `fs.FS` type.
Raw can be used as an argument for the `Run` method.
Server can be used as an argument for the `Run` method.
TLS can be used as an argument for the `Run` method.
TOML reads Configuration from a toml-compatible document file.
WithCharset sets the Charset setting.
WithConfiguration sets the "c" values to the framework's configurations.
WithHostProxyHeader sets a HostProxyHeaders key value pair.
WithKeepAlive sets the `Configuration.KeepAlive` field to the given duration.
WithLogLevel sets the `Configuration.LogLevel` field.
WithOtherValue adds a value based on a key to the Other setting.
WithoutRemoteAddrHeader removes an existing request header name that can be used to validate and parse the client's real IP.
WithoutServerError will cause to ignore the matched "errors" from the main application's `Run/Listen` function.
WithPostMaxMemory sets the maximum post data size that a client can send to the server, this differs from the overall request body size which can be modified by the `context#SetMaxRequestBodySize` or `iris#LimitRequestBodySize`.
WithRemoteAddrHeader adds a new request header name that can be used to validate the client's real IP.
WithRemoteAddrPrivateSubnet adds a new private sub-net to be excluded from `context.RemoteAddr`.
WithSitemap enables the sitemap generator.
WithSocketSharding sets the `Configuration.SocketSharding` field to true.
WithSSLProxyHeader sets a SSLProxyHeaders key value pair.
WithTimeFormat sets the TimeFormat setting.
WithTimeout sets the `Configuration.Timeout` field to the given duration.
YAML reads Configuration from a configuration.yml file.
# Constants
Byte unit helpers.
Byte unit helpers.
Byte unit helpers.
Byte unit helpers.
Byte unit helpers.
HTTP Methods copied from `net/http`.
HTTP Methods copied from `net/http`.
HTTP Methods copied from `net/http`.
HTTP Methods copied from `net/http`.
MethodNone is an iris-specific "virtual" method to store the "offline" routes.
HTTP Methods copied from `net/http`.
HTTP Methods copied from `net/http`.
HTTP Methods copied from `net/http`.
HTTP Methods copied from `net/http`.
HTTP Methods copied from `net/http`.
NoLayout to disable layout for a particular template file A shortcut for the `view#NoLayout`.
Byte unit helpers.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
Contains the enum values of the `Context.GetReferrer()` method, shortcuts of the context subpackage.
RouteError log when a route already exists, shown after the `Build` state, server never starts.
RouteOverlap will overlap the new route to the previous one.
RouteOverride replaces an existing route with the new one, the default rule.
RouteSkip keeps the original route and skips the new one.
SameSite attributes.
SameSite attributes.
SameSite attributes.
SameSite attributes.
RFC 7231, 6.3.3.
RFC 5842, 7.1.
RFC 7231, 6.6.3.
RFC 7231, 6.5.1.
Unofficial Server Errors.
HTTP status codes as registered with IANA.
RFC 7231, 6.5.8.
RFC 7231, 6.2.1.
RFC 7231, 6.3.2.
RFC 8297.
RFC 7231, 6.5.14.
RFC 4918, 11.4.
RFC 7231, 6.5.3.
RFC 7231, 6.4.3.
RFC 7231, 6.6.5.
RFC 7231, 6.5.9.
RFC 7231, 6.6.6.
RFC 3229, 10.4.1.
RFC 4918, 11.5.
RFC 7231, 6.6.1.
HTTP status codes as registered with IANA.
HTTP status codes as registered with IANA.
RFC 7231, 6.5.10.
RFC 4918, 11.3.
RFC 5842, 7.2.
RFC 7231, 6.5.5.
RFC 7540, 9.1.2.
RFC 7231, 6.4.2.
RFC 7231, 6.4.1.
RFC 4918, 11.1.
RFC 6585, 6.
HTTP status codes as registered with IANA.
RFC 7231, 6.3.5.
RFC 7231, 6.3.4.
RFC 7231, 6.5.6.
RFC 2774, 7.
RFC 7231, 6.5.4.
RFC 7231, 6.6.2.
RFC 7232, 4.1.
RFC 7231, 6.3.1.
Unofficial Client Errors.
RFC 7233, 4.1.
RFC 7231, 6.5.2.
RFC 7538, 3.
RFC 7232, 4.2.
RFC 6585, 3.
RFC 2518, 10.1.
RFC 7235, 3.2.
RFC 7233, 4.4.
RFC 7231, 6.5.11.
RFC 6585, 5.
RFC 7231, 6.5.7.
RFC 7231, 6.5.12.
RFC 7231, 6.3.6.
RFC 7231, 6.4.4.
RFC 7231, 6.6.4.
HTTP status codes as registered with IANA.
HTTP status codes as registered with IANA.
RFC 7231, 6.2.2.
RFC 7168, 2.3.3.
RFC 7231, 6.4.7.
HTTP status codes as registered with IANA.
RFC 8470, 5.2.
RFC 6585, 4.
RFC 7235, 3.1.
RFC 7725, 3.
RFC 4918, 11.2.
RFC 7231, 6.5.13.
RFC 7231, 6.5.15.
RFC 7231, 6.4.5.
RFC 2295, 8.1.
Byte unit helpers.
Version is the current version of the Iris Web Framework.
# Variables
Ace view engine.
AllowQuerySemicolons returns a middleware that serves requests by converting any unescaped semicolons(;) in the URL query to ampersands(&).
AutoTLSNoRedirect is a `host.Configurator`.
Blocks view engine.
BuildRevision holds the vcs commit id information of the program's build.
BuildTime holds the vcs commit time information of the program's build.
Cache is a middleware providing server-side cache functionalities to the next handlers, can be used as: `app.Get("/", iris.Cache, aboutHandler)`.
Cache304 sends a `StatusNotModified` (304) whenever the "If-Modified-Since" request header (time) is before the time.Now() + expiresEvery (always compared to their UTC values).
CookieAllowReclaim accepts the Context itself.
CookieAllowSubdomains set to the Cookie Options in order to allow subdomains to have access to the cookies.
CookieCleanPath is a `CookieOption`.
CookieDomain is a CookieOption which sets the cookie's Domain field.
CookieEncoding accepts a value which implements `Encode` and `Decode` methods.
CookieExpires is a `CookieOption`.
CookieHTTPOnly is a `CookieOption`.
CookieOverride is a CookieOption which overrides the cookie explicitly to the given "cookie".
CookiePath is a `CookieOption`.
CookieSameSite sets a same-site rule for cookies to set.
CookieSecure sets the cookie's Secure option if the current request's connection is using TLS.
DefaultTimeoutMessage is the default timeout message which is rendered on expired handlers when timeout handler is registered (see Timeout configuration field).
DirList is the default `DirOptions.DirList` field.
DirListRich can be passed to `DirOptions.DirList` field to override the default file listing appearance.
Django view engine.
ErrEmptyForm is the type error which API users can make use of to check if a form was empty on `Context.ReadForm`.
ErrEmptyFormField reports whether if form value is empty.
ErrHijackNotSupported is returned by the Hijack method to indicate that Hijack feature is not available.
ErrNotFound reports whether a key was not found, useful on post data, versioning feature and others.
ErrPushNotSupported is returned by the Push method to indicate that HTTP/2 Push support is not available.
ErrServerClosed is logged by the standard net/http server when the server is terminated.
ErrStopExecution if returned from a hero middleware or a request-scope dependency stops the handler's execution, see _examples/dependency-injection/basic/middleware.
ErrURLQuerySemicolon is logged by the standard net/http server when the request contains a semicolon (;) wihch, after go1.17 it's not used as a key-value separator character.
FileServer returns a Handler which serves files from a specific system, phyisical, directory or an embedded one.
FromStd converts native http.Handler, http.HandlerFunc & func(w, r, next) to context.Handler.
Handlebars view engine.
HTML view engine.
IsErrCanceled reports whether the "err" is caused by a cancellation or timeout.
IsErrEmptyJSON reports whether the given "err" is caused by a Context.ReadJSON call when the request body didn't start with { or it was totally empty.
IsErrPath can be used at `context#ReadForm` and `context#ReadQuery`.
Jet view engine.
LimitRequestBodySize is a middleware which sets a request body size limit for all next handlers in the chain.
MatchCommonAssets is a simple regex expression which can be used on `DirOptions.PushTargetsRegexp`.
MatchImagesAssets is a simple regex expression that can be passed to the DirOptions.Cache.CompressIgnore field in order to skip compression on already-compressed file types such as images and pdf.
NewConditionalHandler returns a single Handler which can be registered as a middleware.
NewProblem returns a new Problem.
NoCache is a middleware which overrides the Cache-Control, Pragma and Expires headers in order to disable the cache during the browser's back and forward feature.
PrivateError accepts an error and returns a wrapped private one.
Pug view engine.
RegisterMethods adds custom http methods to the "AllMethods" list.
RegisterOnInterrupt registers a global function to call when CTRL+C/CMD+C pressed or a unix kill command received.
StaticCache middleware for caching static files by sending the "Cache-Control" and "Expires" headers to the client.
StatusText returns a text for the HTTP status code.
StripPrefix returns a handler that serves HTTP requests by removing the given prefix from the request URL's Path and invoking the handler h.
TLSNoRedirect is a `host.Configurator` which can be passed as last argument to the `TLS` runner function.
TrimParamFilePart is a middleware which trims any last part after a dot (.) character of the current route's dynamic path parameters.
WebDAVMethods contains a list of WebDAV HTTP Verbs.
WithDynamicHandler enables for dynamic routing by setting the `EnableDynamicHandler` to true.
WithEasyJSON enables the fast easy json marshaler on Context.JSON method.
WithEmptyFormError enables the setting `FireEmptyFormError`.
WithFireMethodNotAllowed enables the FireMethodNotAllowed setting.
WithGlobalConfiguration will load the global yaml configuration file from the home directory and it will set/override the whole app's configuration to that file's contents.
WithLowercaseRouting enables for lowercase routing by setting the `ForceLowercaseRoutes` to true.
WithOptimizations can force the application to optimize for the best performance where is possible.
WithoutAutoFireStatusCode sets the DisableAutoFireStatusCode setting to true.
WithoutBanner is a conversion for the `WithoutStartupLog` option.
WithoutBodyConsumptionOnUnmarshal disables BodyConsumptionOnUnmarshal setting.
WithoutInterruptHandler disables the automatic graceful server shutdown when control/cmd+C pressed.
WithoutPathCorrection disables the PathCorrection setting.
WithoutPathCorrectionRedirection disables the PathCorrectionRedirection setting.
WithoutStartupLog turns off the information send, once, to the terminal when the main server is open.
WithPathEscape sets the EnablePathEscape setting to true.
WithPathIntelligence enables the EnablePathIntelligence setting.
WithProtoJSON enables the proto marshaler on Context.JSON method.
WithResetOnFireErrorCode sets the ResetOnFireErrorCode setting to true.
WithTunneling is the `iris.Configurator` for the `iris.Configuration.Tunneling` field.
WithURLParamSeparator sets the URLParamSeparator setting to "sep".
XMLMap wraps a map[string]interface{} to compatible xml marshaler, in order to be able to render maps as XML on the `Context.XML` method.
# Structs
Application is responsible to manage the state of the application.
Configuration holds the necessary settings for an Iris Application instance.
ContextPatches contains the available global Iris context modifications.
ContextWrapper is a wrapper for handlers which expect a T instead of iris.Context.
ContextWriterPatches features the context's writers patches.
GlobalPatches is a singleton features a uniform way to apply global/package-level modifications.
Singleton is a structure which can be used as an embedded field on struct/controllers that should be marked as singletons on `PartyConfigure` or `MVC` Applications.
# Type aliases
Configurator is just an interface which accepts the framework instance.
Runner is just an interface which accepts the framework instance and returns an error.