Categorygithub.com/azber/iris
modulepackage
3.0.0-beta+incompatible
Repository: https://github.com/azber/iris.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
35
Dependents
0
Files
2.8k SLOC

# README

Iris Logo

Travis Widget Release Widget Report Widget License Widget Gitter Widget Documentation Widget

Benchmark Wizzard Processing Time Horizontal Graph

$ cat main.go

package main

import  "github.com/kataras/iris"

func main() {
	iris.Get("/hi_json", func(c *iris.Context) {
		c.JSON(200, iris.Map{
			"Name": "Iris",
			"Age":  2,
		})
	})
	iris.Listen(":8080")
}

Learn about configuration and 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

Features

  • Focus on high performance
  • Robust routing & 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 editor
  • Content negotiation & streaming
  • Transport Layer Security

Docs & Community

If you'd like to discuss this package, or ask questions about it, feel free to

  • Post an issue or idea here
  • Chat with us

Open debates

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.

Benchmark Wizzard Processing Time Horizontal Graph

Please click here to view all detailed benchmarks.

Testing

Iris suggests you to use this new suite to test your API. Httpexpect supports fasthttp & Iris after recommandation. Its author is very active so I believe its a promising library. You can view examples here and here.

Versioning

Current: v3.0.0-beta

Iris is an active project

Read more about Semantic Versioning 2.0.0

Todo

for the next release 'v3'

  • 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.

If you're willing to donate click here

People

The author of Iris is @kataras

License

This project is licensed under the Apache License 2.0.

License can be found here.

# Packages

File bindings/form.go source code from https://github.com/monoculum/formame.
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
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
Package tests emptyWhy empty? The only reason I don't make unit tests is because I think the whole story here is wrong.
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 three parameters first is the request path (string) second is the custom struct (interface{}) which can be anything that has a *iris.Context as field third are the common middlewares, is optional parameter Recommend to use when you retrieve data from an external database, and the router-performance is not the (only) thing which slows the server's overall performance.
Close is used to close the net.Listener of the standalone http server which has already running via .Listen.
Config returns the configs.
Connect registers a route for the Connect http method.
ConvertToHandlers accepts list of HandlerFunc and returns list of Handler this can be renamed to convertToMiddleware also because it returns a list of []Handler which is what Middleware is.
Delete registers a route for the Delete http method.
EmitError executes the handler of the given error http status code.
Favicon serves static favicon accepts 2 parameters, second is optionally 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) returns an error if something goes bad.
Get registers a route for the Get http method.
GetParamsLen returns the parameters length from a given path.
Handle registers a route to the server's router if empty method is passed then registers handler(s) for all methods, same as .Any.
HandleAnnotated registers a route handler using a Struct implements iris.Handler (as anonymous property) which it's metadata has the form of `method:"path"` and returns the route and an error if any occurs handler is passed by func(urstruct MyStruct) Serve(ctx *Context) {} HandleAnnotated will be deprecated until the final v3 !.
HandleFunc registers a route with a method, path string, and a handler.
Head registers a route for the Head http method.
HTTPErrorHandlerFunc creates a handler which is responsible to send a particular error to the client.
JoinMiddleware uses to create a copy of all middleware and return them in order to use inside the node.
Listen starts the standalone http server which listens to the addr parameter which as the form of host:port or just 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 or just 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 or just 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")).
ListenWithErr starts the standalone http server which listens to the addr parameter which as the form of host:port or just 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")).
Logger returns the logger.
New creates and returns a new iris station.
NewRoute creates, from a path string, and a slice of HandlerFunc.
OnError Registers a handler for a specific http error status.
OnNotFound sets the handler for http status 404, default is a response with text: 'Not Found' and status: 404.
OnPanic sets the handler for http status 500, default is a response with text: The server encountered an unexpected condition which prevented it from fulfilling the request.
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.
Plugins returns the plugin container.
Post
Post registers a route for the Post http method.
Put registers a route for the Put http method.
Rest returns the rest render.
RouteConflicts checks for route's middleware conflicts.
Server returns the server.
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.
StaticFS registers a route which serves a system directory generates an index page which list all files uses compression which file cache, 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: "".
StaticHandlerFunc returns a HandlerFunc 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: "".
StatusText returns a text for the HTTP status code.
Templates returns the template render.
ToHandler converts an http.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 methodd.
Credits to Manish Singh @kryptodev for URLEncode */ 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 appends a middleware to the route or to the router if it's called from router.
UseFunc same as Use but it accepts/receives ...HandlerFunc instead of ...Handler form of acceptable: func(c *iris.Context){//first middleware}, func(c *iris.Context){//second middleware}.
Websocket returns the websocket server.

# Constants

ContentBINARY is the string of application/octet-stream response headers.
ContentDisposition "Content-Disposition".
ContentHTML is the string of text/html response headers.
ContentLength represents the header["Content-Length"].
ContentType represents the header["Content-Type"].
DefaultUserAgent default to 'iris' but it is not used anywhere yet.
IfModifiedSince "If-Modified-Since".
LastModified "Last-Modified".
MatchEverythingByte is just a byte of '*" rune/char.
MethodConnect "CONNECT".
MethodDelete "DELETE".
MethodGet "GET".
MethodHead "HEAD".
MethodOptions "OPTIONS".
MethodPatch "PATCH".
MethodPost "POST".
MethodPut "PUT".
MethodTrace "TRACE".
ParameterStartByte is very used on the node, it's just contains the byte for the ':' rune/char.
Slash is just a string of "/".
SlashByte is just a byte of '/' rune/char.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
taken from net/http.
TimeFormat default time format for any kind of datetime parsing.
No description provided by the author

# Variables

AllMethods "GET", "POST", "PUT", "DELETE", "CONNECT", "HEAD", "PATCH", "OPTIONS", "TRACE".
No description provided by the author
No description provided by the author
DefaultIris in order to use iris.Get(...,...) we need a default Iris on the package level.
No description provided by the author
No description provided by the author
ErrFlashNotFound returns an error with message: 'Unable to get flash message.
ErrHandleAnnotated returns an error with message: 'HandleAnnotated parse: +specific error(s)'.
ErrHandler returns na error with message: 'Passed argument is not func(*Context) neither an object which implements the iris.Handler with Serve(ctx *Context) It seems to be a +type Points to: +pointer.'.
ErrPluginActivate returns an error with message: 'While trying to activate plugin '+plugin name'.
ErrPluginAlreadyExists returns an error with message: 'Cannot activate the same plugin again, plugin '+plugin name[+plugin description]' is already exists'.
ErrPluginRemoveEmptyName returns an error with message: 'Plugin with an empty name cannot be removed'.
ErrPluginRemoveNoPlugins returns an error with message: 'No plugins are registed yet, you cannot remove a plugin from an empty list!'.
ErrPluginRemoveNotFound returns an error with message: 'Cannot remove a plugin which doesn't exists'.
ErrServeContent returns an error with message: 'While trying to serve content to the client.
ErrSessionNil returns an error with message: 'Unable to set session, Config().Session.Provider is nil, please refer to the docs!'.
ErrTemplateExecute returns an error with message:'Unable to execute a template.
No description provided by the author
No description provided by the author
No description provided by the author
MethodConnectBytes []byte("CONNECT").
No description provided by the author
No description provided by the author
No description provided by the author

# Structs

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
PluginContainer is the base container of all Iris, registed plugins.
No description provided by the author

# 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
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
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
No description provided by the author
No description provided by the author