modulepackage
3.0.0-rc.3+incompatible
Repository: https://github.com/drillbits/iris.git
Documentation: pkg.go.dev
# README
The fastest web framework for Go.
$ cat test_json.go
package main
import (
"github.com/kataras/iris"
)
func main() {
// render JSON
iris.Get("/hi_json", func(c *iris.Context) {
c.JSON(iris.StatusOK, iris.Map{
"Name": "Iris",
"Born": "13 March 2016",
"Stars": 3404,
})
})
iris.Listen(":8080")
}
Learn more about render.
Installation
The only requirement is Go 1.6
$ go get -u github.com/kataras/iris/iris
If you are connected to the Internet through China click here
FAQ
You can find answers by exploring these questions.
Features
- Focus on high performance
- Robust routing supports static and wildcard subdomains
- View system supporting 5+ template engines
- Highly scalable Websocket API with custom events
- Sessions support with GC, memory & redis providers
- Middlewares & Plugins were never be easier
- Full REST API
- Custom HTTP Errors
- Typescript compiler + Browser-based editor
- Content negotiation & streaming
- Transport Layer Security
- Reload on source code changes
- OAuth, OAuth2 supporting 27+ API providers
- JSON Web Tokens
- and more
| Name | Description | Usage |
|---|---|---|
| Basicauth Middleware | HTTP Basic authentication | example 1, example 2, book section |
| JWT Middleware | JSON Web Tokens | example , book section |
| Cors Middleware | Cross Origin Resource Sharing W3 specification | how to use |
| Secure Middleware | Facilitates some quick security wins | example |
| I18n Middleware | Simple internationalization | example, book section |
| Recovery Middleware | Safety recover the station from panic | example |
| Logger Middleware | Logs every request | example, book section |
| Editor Plugin | Alm-tools, a typescript online IDE/Editor | book section |
| Typescript Plugin | Auto-compile client-side typescript files | book section |
| OAuth,OAuth2 Plugin | User Authentication was never be easier, supports >27 providers | example, book section |
| Iris control Plugin | Basic (browser-based) control over your Iris station | example, book section |
Docs & Community
If you'd like to discuss this package, or ask questions about it, feel free to
Open debates
- Contribute: New website and logo for Iris
- E-book Cover - Which one you suggest?
- Feature request: session.Exists
TIP Be sure to read the history for Migrating from 2.x to 3.x.
Philosophy
The Iris philosophy is to provide robust tooling for HTTP, making it a great solution for single page applications, web sites, hybrids, or public HTTP APIs.
Iris does not force you to use any specific ORM or template engine. With support for the most used template engines, you can quickly craft the perfect application.
Benchmarks
This Benchmark suite aims to compare the whole HTTP request processing between Go web frameworks.
Please click here to view all detailed benchmarks.
Testing
Tests are located to the iris-contrib/tests repository, community should write some code there! I recommend writing your API tests using this new library, httpexpect which supports Iris and fasthttp now, after my request here.
Versioning
Current: v3.0.0-rc.3
Iris is an active project
Read more about Semantic Versioning 2.0.0
- http://semver.org/
- https://en.wikipedia.org/wiki/Software_versioning
- https://wiki.debian.org/UpstreamGuide#Releases_and_Versions
Todo
for the next release 'v3'
- Dynamic/Wildcard subdomains.
- Create server & client side (js) library for .on('event', func action(...)) / .emit('event')... (like socket.io but supports only websocket).
- Find and provide support for the most stable template engine and be able to change it via the configuration, keep html/templates support.
- Extend, test and publish to the public the Iris' cmd.
- Route naming and html url func, requested here.
- Move middleware & plugins to other repository
If you're willing to donate click here!
People
A big thanks goes to all people who help building this framework with feature-requests, bug reports and more!
The author of Iris is @kataras.
License
This project is licensed under the Apache License 2.0.
License can be found here.
# Packages
Package config defines the default settings and semantic variables.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
# Functions
Any registers a route for ALL of the http methods (Get,Post,Put,Head,Patch,Options,Connect,Delete).
API converts & registers a custom struct to the router receives two parameters first is the request path (string) second is the custom struct (interface{}) which can be anything that has a *iris.Context as field.
Close terminates the server and panic if error occurs.
CloseWithErr terminates the server and returns an error if any.
Connect registers a route for the Connect http method.
Delete registers a route for the Delete http method.
EmitError fires a custom http error handler to the client
if no custom error defined with this statuscode, then iris creates one, and once at runtime.
Favicon serves static favicon accepts 2 parameters, second is optional favPath (string), declare the system directory path of the __.ico requestPath (string), it's the route's path, by default this is the "/favicon.ico" because some browsers tries to get this by default first, you can declare your own path if you have more than one favicon (desktop, mobile and so on)
this func will add a route for you which will static serve the /yuorpath/yourfile.ico to the /yourfile.ico (nothing special that you can't handle by yourself) Note that you have to call it on every favicon you have to serve automatically (dekstop, mobile and so on)
panics on error.
Get registers a route for the Get http method.
Handle registers a route to the server's router if empty method is passed then registers handler(s) for all methods, same as .Any, but returns nil as result.
HandleFunc registers and returns a route with a method string, path string and a handler registedPath is the relative url path.
Head registers a route for the Head http method.
Listen starts the standalone http server which listens to the addr parameter which as the form of host:port
It panics on error if you need a func to return an error use the ListenWithErr ex: iris.Listen(":8080").
ListenTLS Starts a https server with certificates, if you use this method the requests of the form of 'http://' will fail only https:// connections are allowed which listens to the addr parameter which as the form of host:port
It panics on error if you need a func to return an error use the ListenTLSWithErr ex: iris.ListenTLS(":8080","yourfile.cert","yourfile.key").
ListenTLSWithErr Starts a https server with certificates, if you use this method the requests of the form of 'http://' will fail only https:// connections are allowed which listens to the addr parameter which as the form of host:port
It returns an error you are responsible how to handle this if you need a func to panic on error use the ListenTLS ex: log.Fatal(iris.ListenTLSWithErr(":8080","yourfile.cert","yourfile.key")).
ListenUNIX starts the process of listening to the new requests using a 'socket file', this works only on unix panics on error.
ListenUNIXWithErr starts the process of listening to the new requests using a 'socket file', this works only on unix returns an error if something bad happens when trying to listen to.
ListenWithErr starts the standalone http server which listens to the addr parameter which as the form of host:port
It returns an error you are responsible how to handle this if you need a func to panic on error use the Listen ex: log.Fatal(iris.ListenWithErr(":8080")).
Lookup returns a registed route by its name.
Lookups returns all registed routes.
Must panics on error, it panics on registed iris' logger.
MustUse registers Handler middleware to the beginning, prepends them instead of append
Use it when you want to add a global middleware to all parties, to all routes in all subdomains It can be called after other, (but before .Listen of course).
MustUseFunc registers HandlerFunc middleware to the beginning, prepends them instead of append
Use it when you want to add a global middleware to all parties, to all routes in all subdomains It can be called after other, (but before .Listen of course).
New creates and returns a new Iris station aka Framework.
NoListen is useful only when you want to test Iris, it doesn't starts the server but it configures and returns it.
OnError registers a custom http error handler.
Options registers a route for the Options http method.
ParseParams receives a string and returns PathParameters (slice of PathParameter) received string must have this form: key1=value1,key2=value2...
Party is just a group joiner of routes which have the same prefix and share same middleware(s) also.
Patch registers a route for the Patch http method.
Path used to check arguments with the route's named parameters and return the correct url if parse failed returns empty string.
Post registers a route for the Post http method.
Put registers a route for the Put http method.
Static registers a route which serves a system directory this doesn't generates an index page which list all files no compression is used also, for these features look at StaticFS func accepts three parameters first parameter is the request url path (string) second parameter is the system directory (string) third parameter is the level (int) of stripSlashes * stripSlashes = 0, original path: "/foo/bar", result: "/foo/bar" * stripSlashes = 1, original path: "/foo/bar", result: "/bar" * stripSlashes = 2, original path: "/foo/bar", result: "".
StaticContent serves bytes, memory cached, on the reqPath a good example of this is how the websocket server uses that to auto-register the /iris-ws.js.
StaticFS registers a route which serves a system directory this is the fastest method to serve static files generates an index page which list all files if you use this method it will generate compressed files also think this function as small fileserver with http accepts three parameters first parameter is the request url path (string) second parameter is the system directory (string) third parameter is the level (int) of stripSlashes * stripSlashes = 0, original path: "/foo/bar", result: "/foo/bar" * stripSlashes = 1, original path: "/foo/bar", result: "/bar" * stripSlashes = 2, original path: "/foo/bar", result: "".
StaticHandler returns a Handler to serve static system directory Accepts 5 parameters
first is the systemPath (string) Path to the root directory to serve files from.
StaticServe serves a directory as web resource it's the simpliest form of the Static* functions Almost same usage as StaticWeb accepts only one required parameter which is the systemPath ( the same path will be used to register the GET&HEAD routes) if second parameter is empty, otherwise the requestPath is the second parameter it uses gzip compression (compression on each request, no file cache).
StaticWeb same as Static but if index.html exists and request uri is '/' then display the index.html's contents accepts three parameters first parameter is the request url path (string) second parameter is the system directory (string) third parameter is the level (int) of stripSlashes * stripSlashes = 0, original path: "/foo/bar", result: "/foo/bar" * stripSlashes = 1, original path: "/foo/bar", result: "/bar" * stripSlashes = 2, original path: "/foo/bar", result: "" * if you don't know what to put on stripSlashes just 1.
StatusText returns a text for the HTTP status code.
TemplateString executes a template and returns its result as string, useful when you want it for sending rich e-mails returns empty string on error.
ToHandler converts an httapi.Handler or http.HandlerFunc to an iris.Handler.
ToHandlerFastHTTP converts an fasthttp.RequestHandler to an iris.Handler.
ToHandlerFunc converts an http.Handler or http.HandlerFunc to an iris.HandlerFunc.
Trace registers a route for the Trace http method.
URL returns the subdomain+ host + Path(...optional named parameters if route is dynamic) returns an empty string if parse is failed.
URLEncode returns the path encoded as url useful when you want to pass something to a database and be valid to retrieve it via context.Param use it only for special cases, when the default behavior doesn't suits you.
Use registers Handler middleware.
UseFunc registers HandlerFunc middleware.
# Constants
AmberEngine conversion for config.AmberEngine.
DefaultEngine conversion for config.DefaultEngine.
HTMLEngine conversion for config.HTMLEngine.
JadeEngine conversion for config.JadeEngine.
MarkdownEngine conversion for config.MarkdownEngine.
MethodConnect "CONNECT".
MethodDelete "DELETE".
MethodGet "GET".
MethodHead "HEAD".
MethodOptions "OPTIONS".
MethodPatch "PATCH".
MethodPost "POST".
MethodPut "PUT".
MethodTrace "TRACE".
NoEngine conversion for config.NoEngine.
NoLayout to disable layout for a particular template file conversion for config.NoLayout.
PongoEngine conversion for config.PongoEngine.
StatusAccepted http status '202'.
StatusBadGateway http status '502'.
StatusBadRequest http status '400'.
StatusConflict http status '409'.
StatusContinue http status '100'.
StatusCreated http status '201'.
StatusExpectationFailed http status '417'.
StatusForbidden http status '403'.
StatusFound http status '302'.
StatusGatewayTimeout http status '504'.
StatusGone http status '410'.
StatusHTTPVersionNotSupported http status '505'.
StatusInternalServerError http status '500'.
StatusLengthRequired http status '411'.
StatusMethodNotAllowed http status '405'.
StatusMovedPermanently http status '301'.
StatusMultipleChoices http status '300'.
StatusNetworkAuthenticationRequired http status '511'.
StatusNoContent http status '204'.
StatusNonAuthoritativeInfo http status '203'.
StatusNotAcceptable http status '406'.
StatusNotFound http status '404'.
StatusNotImplemented http status '501'.
StatusNotModified http status '304'.
StatusOK http status '200'.
StatusPartialContent http status '206'.
StatusPaymentRequired http status '402'.
StatusPreconditionFailed http status '412'.
StatusPreconditionRequired http status '428'.
StatusProxyAuthRequired http status '407'.
StatusRequestedRangeNotSatisfiable http status '416'.
StatusRequestEntityTooLarge http status '413'.
StatusRequestHeaderFieldsTooLarge http status '431'.
StatusRequestTimeout http status '408'.
StatusRequestURITooLong http status '414'.
StatusResetContent http status '205'.
StatusSeeOther http status '303'.
StatusServiceUnavailable http status '503'.
StatusSwitchingProtocols http status '101'.
StatusTeapot http status '418'.
StatusTemporaryRedirect http status '307'.
StatusTooManyRequests http status '429'.
StatusUnauthorized http status '401'.
StatusUnavailableForLegalReasons http status '451'.
StatusUnsupportedMediaType http status '415'.
StatusUseProxy http status '305'.
Version of the iris.
# Variables
AllMethods "GET", "POST", "PUT", "DELETE", "CONNECT", "HEAD", "PATCH", "OPTIONS", "TRACE".
Default entry, use it with iris.$anyPublicFunc.
Default entry, use it with iris.$anyPublicFunc.
Default entry, use it with iris.$anyPublicFunc.
Default entry, use it with iris.$anyPublicFunc.
Default entry, use it with iris.$anyPublicFunc.
SkipBannerFlag, if enabled then means that this instance ran propably by an external software, which can disable the banner output by the command line argument '-s'.
Default entry, use it with iris.$anyPublicFunc.
# Structs
No description provided by the author
Framework is our God |\| Google.Search('Greek mythology Iris')
Implements the FrameworkAPI.
No description provided by the author
Server the http server.
# Interfaces
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
# Type aliases
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author