go-packages/iris
1
0
Fork 0
mirror of https://github.com/kataras/iris.git synced 2025-03-15 18:56:29 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

configuration update

Gerasimos (Makis) Maropoulos 2020-06-18 09:47:07 +03:00
parent 18afa86fa4
commit 94f3a048a1
No known key found for this signature in database
GPG Key ID: 5DBE766BD26A54E7
5 changed files with 1373 additions and 1217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

494
Configuration.md

@ -22,6 +22,323 @@ config := iris.WithConfiguration(iris.Configuration {
app.Listen(":8080", config) app.Listen(":8080", config)
``` ```
List of all available settings:
```go
// Tunnel is the Tunnels field of the TunnelingConfiguration structure.
type Tunnel struct {
// Name is the only one required field,
// it is used to create and close tunnels, e.g. "MyApp".
// If this field is not empty then ngrok tunnels will be created
// when the iris app is up and running.
Name string `json:"name" yaml:"Name" toml:"Name"`
// Addr is basically optionally as it will be set through
// Iris built-in Runners, however, if `iris.Raw` is used
// then this field should be set of form 'hostname:port'
// because framework cannot be aware
// of the address you used to run the server on this custom runner.
Addr string `json:"addr,omitempty" yaml:"Addr" toml:"Addr"`
}
// TunnelingConfiguration contains configuration
// for the optional tunneling through ngrok feature.
// Note that the ngrok should be already installed at the host machine.
type TunnelingConfiguration struct {
// AuthToken field is optionally and can be used
// to authenticate the ngrok access.
// ngrok authtoken <YOUR_AUTHTOKEN>
AuthToken string `json:"authToken,omitempty" yaml:"AuthToken" toml:"AuthToken"`
// No...
// Config is optionally and can be used
// to load ngrok configuration from file system path.
//
// If you don't specify a location for a configuration file,
// ngrok tries to read one from the default location $HOME/.ngrok2/ngrok.yml.
// The configuration file is optional; no error is emitted if that path does not exist.
// Config string `json:"config,omitempty" yaml:"Config" toml:"Config"`
// Bin is the system binary path of the ngrok executable file.
// If it's empty then the framework will try to find it through system env variables.
Bin string `json:"bin,omitempty" yaml:"Bin" toml:"Bin"`
// WebUIAddr is the web interface address of an already-running ngrok instance.
// Iris will try to fetch the default web interface address(http://127.0.0.1:4040)
// to determinate if a ngrok instance is running before try to start it manually.
// However if a custom web interface address is used,
// this field must be set e.g. http://127.0.0.1:5050.
WebInterface string `json:"webInterface,omitempty" yaml:"WebInterface" toml:"WebInterface"`
// Region is optionally, can be used to set the region which defaults to "us".
// Available values are:
// "us" for United States
// "eu" for Europe
// "ap" for Asia/Pacific
// "au" for Australia
// "sa" for South America
// "jp" forJapan
// "in" for India
Region string `json:"region,omitempty" yaml:"Region" toml:"Region"`
// Tunnels the collection of the tunnels.
// One tunnel per Iris Host per Application, usually you only need one.
Tunnels []Tunnel `json:"tunnels" yaml:"Tunnels" toml:"Tunnels"`
}
// Configuration holds the necessary settings for an Iris Application instance.
// All fields are optionally, the default values will work for a common web application.
//
// A Configuration value can be passed through `WithConfiguration` Configurator.
// Usage:
// conf := iris.Configuration{ ... }
// app := iris.New()
// app.Configure(iris.WithConfiguration(conf)) OR
// app.Run/Listen(..., iris.WithConfiguration(conf)).
type Configuration struct {
// LogLevel is the log level the application should use to output messages.
// Logger, by default, is mostly used on Build state but it is also possible
// that debug error messages could be thrown when the app is running, e.g.
// when malformed data structures try to be sent on Client (i.e Context.JSON/JSONP/XML...).
//
// Defaults to "info". Possible values are:
// * "disable"
// * "fatal"
// * "error"
// * "warn"
// * "info"
// * "debug"
LogLevel string `json:"logLevel" yaml:"LogLevel" toml:"LogLevel" env:"LOG_LEVEL"`
// Tunneling can be optionally set to enable ngrok http(s) tunneling for this Iris app instance.
// See the `WithTunneling` Configurator too.
Tunneling TunnelingConfiguration `json:"tunneling,omitempty" yaml:"Tunneling" toml:"Tunneling"`
// IgnoreServerErrors will cause to ignore the matched "errors"
// from the main application's `Run` function.
// This is a slice of string, not a slice of error
// users can register these errors using yaml or toml configuration file
// like the rest of the configuration fields.
//
// See `WithoutServerError(...)` function too.
//
// Example: https://github.com/kataras/iris/tree/master/_examples/http-server/listen-addr/omit-server-errors
//
// Defaults to an empty slice.
IgnoreServerErrors []string `json:"ignoreServerErrors,omitempty" yaml:"IgnoreServerErrors" toml:"IgnoreServerErrors"`
// DisableStartupLog if set to true then it turns off the write banner on server startup.
//
// Defaults to false.
DisableStartupLog bool `json:"disableStartupLog,omitempty" yaml:"DisableStartupLog" toml:"DisableStartupLog"`
// DisableInterruptHandler if set to true then it disables the automatic graceful server shutdown
// when control/cmd+C pressed.
// Turn this to true if you're planning to handle this by your own via a custom host.Task.
//
// Defaults to false.
DisableInterruptHandler bool `json:"disableInterruptHandler,omitempty" yaml:"DisableInterruptHandler" toml:"DisableInterruptHandler"`
// DisablePathCorrection disables the correcting
// and redirecting or executing directly the handler of
// the requested path to the registered path
// for example, if /home/ path is requested but no handler for this Route found,
// then the Router checks if /home handler exists, if yes,
// (permanent)redirects the client to the correct path /home.
//
// See `DisablePathCorrectionRedirection` to enable direct handler execution instead of redirection.
//
// Defaults to false.
DisablePathCorrection bool `json:"disablePathCorrection,omitempty" yaml:"DisablePathCorrection" toml:"DisablePathCorrection"`
// DisablePathCorrectionRedirection works whenever configuration.DisablePathCorrection is set to false
// and if DisablePathCorrectionRedirection set to true then it will fire the handler of the matching route without
// the trailing slash ("/") instead of send a redirection status.
//
// Defaults to false.
DisablePathCorrectionRedirection bool `json:"disablePathCorrectionRedirection,omitempty" yaml:"DisablePathCorrectionRedirection" toml:"DisablePathCorrectionRedirection"`
// EnablePathIntelligence if set to true,
// the router will redirect HTTP "GET" not found pages to the most closest one path(if any). For example
// you register a route at "/contact" path -
// a client tries to reach it by "/cont", the path will be automatic fixed
// and the client will be redirected to the "/contact" path
// instead of getting a 404 not found response back.
//
// Defaults to false.
EnablePathIntelligence bool `json:"enablePathIntelligence,omitempty" yaml:"EnablePathIntelligence" toml:"EnablePathIntelligence"`
// EnablePathEscape when is true then its escapes the path and the named parameters (if any).
// When do you need to Disable(false) it:
// accepts parameters with slash '/'
// Request: http://localhost:8080/details/Project%2FDelta
// ctx.Param("project") returns the raw named parameter: Project%2FDelta
// which you can escape it manually with net/url:
// projectName, _ := url.QueryUnescape(c.Param("project").
//
// Defaults to false.
EnablePathEscape bool `json:"enablePathEscape,omitempty" yaml:"EnablePathEscape" toml:"EnablePathEscape"`
// ForceLowercaseRouting if enabled, converts all registered routes paths to lowercase
// and it does lowercase the request path too for matching.
//
// Defaults to false.
ForceLowercaseRouting bool `json:"forceLowercaseRouting,omitempty" yaml:"ForceLowercaseRouting" toml:"ForceLowercaseRouting"`
// FireMethodNotAllowed if it's true router checks for StatusMethodNotAllowed(405) and
// fires the 405 error instead of 404
// Defaults to false.
FireMethodNotAllowed bool `json:"fireMethodNotAllowed,omitempty" yaml:"FireMethodNotAllowed" toml:"FireMethodNotAllowed"`
// DisableAutoFireStatusCode if true then it turns off the http error status code
// handler automatic execution on error code from a `Context.StatusCode` call.
// By-default a custom http error handler will be fired when "Context.StatusCode(errorCode)" called.
//
// Defaults to false.
DisableAutoFireStatusCode bool `json:"disableAutoFireStatusCode,omitempty" yaml:"DisableAutoFireStatusCode" toml:"DisableAutoFireStatusCode"`
// ResetOnFireErrorCode if true then any previously response body or headers through
// response recorder or gzip writer will be ignored and the router
// will fire the registered (or default) HTTP error handler instead.
// See `core/router/handler#FireErrorCode` and `Context.EndRequest` for more details.
//
// Read more at: https://github.com/kataras/iris/issues/1531
//
// Defaults to false.
ResetOnFireErrorCode bool `json:"resetOnFireErrorCode,omitempty" yaml:"ResetOnFireErrorCode" toml:"ResetOnFireErrorCode"`
// EnableOptimization when this field is true
// then the application tries to optimize for the best performance where is possible.
//
// Defaults to false.
EnableOptimizations bool `json:"enableOptimizations,omitempty" yaml:"EnableOptimizations" toml:"EnableOptimizations"`
// DisableBodyConsumptionOnUnmarshal manages the reading behavior of the context's body readers/binders.
// If set to true then it
// disables the body consumption by the `context.UnmarshalBody/ReadJSON/ReadXML`.
//
// By-default io.ReadAll` is used to read the body from the `context.Request.Body which is an `io.ReadCloser`,
// if this field set to true then a new buffer will be created to read from and the request body.
// The body will not be changed and existing data before the
// context.UnmarshalBody/ReadJSON/ReadXML will be not consumed.
DisableBodyConsumptionOnUnmarshal bool `json:"disableBodyConsumptionOnUnmarshal,omitempty" yaml:"DisableBodyConsumptionOnUnmarshal" toml:"DisableBodyConsumptionOnUnmarshal"`
// FireEmptyFormError returns if set to tue true then the `context.ReadBody/ReadForm`
// will return an `iris.ErrEmptyForm` on empty request form data.
FireEmptyFormError bool `json:"fireEmptyFormError,omitempty" yaml:"FireEmptyFormError" yaml:"FireEmptyFormError"`
// TimeFormat time format for any kind of datetime parsing
// Defaults to "Mon, 02 Jan 2006 15:04:05 GMT".
TimeFormat string `json:"timeFormat,omitempty" yaml:"TimeFormat" toml:"TimeFormat"`
// Charset character encoding for various rendering
// used for templates and the rest of the responses
// Defaults to "utf-8".
Charset string `json:"charset,omitempty" yaml:"Charset" toml:"Charset"`
// PostMaxMemory sets the maximum post data size
// that a client can send to the server, this differs
// from the overral request body size which can be modified
// by the `context#SetMaxRequestBodySize` or `iris#LimitRequestBodySize`.
//
// Defaults to 32MB or 32 << 20 if you prefer.
PostMaxMemory int64 `json:"postMaxMemory" yaml:"PostMaxMemory" toml:"PostMaxMemory"`
// +----------------------------------------------------+
// | Context's keys for values used on various featuers |
// +----------------------------------------------------+
// Context values' keys for various features.
//
// LocaleContextKey is used by i18n to get the current request's locale, which contains a translate function too.
//
// Defaults to "iris.locale".
LocaleContextKey string `json:"localeContextKey,omitempty" yaml:"LocaleContextKey" toml:"LocaleContextKey"`
// LanguageContextKey is the context key which a language can be modified by a middleware.
// It has the highest priority over the rest and if it is empty then it is ignored,
// if it set to a static string of "default" or to the default language's code
// then the rest of the language extractors will not be called at all and
// the default language will be set instead.
//
// Use with `Context.SetLanguage("el-GR")`.
//
// See `i18n.ExtractFunc` for a more organised way of the same feature.
// Defaults to "iris.locale.language".
LanguageContextKey string `json:"languageContextKey,omitempty" yaml:"LanguageContextKey" toml:"LanguageContextKey"`
// VersionContextKey is the context key which an API Version can be modified
// via a middleware through `SetVersion` method, e.g. `ctx.SetVersion("1.0, 1.1")`.
// Defaults to "iris.api.version".
VersionContextKey string `json:"versionContextKey" yaml:"VersionContextKey" toml:"VersionContextKey"`
// GetViewLayoutContextKey is the key of the context's user values' key
// which is being used to set the template
// layout from a middleware or the main handler.
// Overrides the parent's or the configuration's.
//
// Defaults to "iris.ViewLayout"
ViewLayoutContextKey string `json:"viewLayoutContextKey,omitempty" yaml:"ViewLayoutContextKey" toml:"ViewLayoutContextKey"`
// GetViewDataContextKey is the key of the context's user values' key
// which is being used to set the template
// binding data from a middleware or the main handler.
//
// Defaults to "iris.viewData"
ViewDataContextKey string `json:"viewDataContextKey,omitempty" yaml:"ViewDataContextKey" toml:"ViewDataContextKey"`
// RemoteAddrHeaders are the allowed request headers names
// that can be valid to parse the client's IP based on.
// By-default no "X-" header is consired safe to be used for retrieving the
// client's IP address, because those headers can manually change by
// the client. But sometimes are useful e.g., when behind a proxy
// you want to enable the "X-Forwarded-For" or when cloudflare
// you want to enable the "CF-Connecting-IP", inneed you
// can allow the `ctx.RemoteAddr()` to use any header
// that the client may sent.
//
// Defaults to an empty map but an example usage is:
// RemoteAddrHeaders {
// "X-Real-Ip": true,
// "X-Forwarded-For": true,
// "CF-Connecting-IP": true,
// }
//
// Look `context.RemoteAddr()` for more.
RemoteAddrHeaders map[string]bool `json:"remoteAddrHeaders,omitempty" yaml:"RemoteAddrHeaders" toml:"RemoteAddrHeaders"`
// RemoteAddrPrivateSubnets defines the private sub-networks.
// They are used to be compared against
// IP Addresses fetched through `RemoteAddrHeaders` or `Context.Request.RemoteAddr`.
// For details please navigate through: https://github.com/kataras/iris/issues/1453
// Defaults to:
// {
// Start: net.ParseIP("10.0.0.0"),
// End: net.ParseIP("10.255.255.255"),
// },
// {
// Start: net.ParseIP("100.64.0.0"),
// End: net.ParseIP("100.127.255.255"),
// },
// {
// Start: net.ParseIP("172.16.0.0"),
// End: net.ParseIP("172.31.255.255"),
// },
// {
// Start: net.ParseIP("192.0.0.0"),
// End: net.ParseIP("192.0.0.255"),
// },
// {
// Start: net.ParseIP("192.168.0.0"),
// End: net.ParseIP("192.168.255.255"),
// },
// {
// Start: net.ParseIP("198.18.0.0"),
// End: net.ParseIP("198.19.255.255"),
// }
//
// Look `Context.RemoteAddr()` for more.
RemoteAddrPrivateSubnets []netutil.IPRange `json:"remoteAddrPrivateSubnets" yaml:"RemoteAddrPrivateSubnets" toml:"RemoteAddrPrivateSubnets"`
// SSLProxyHeaders defines the set of header key values
// that would indicate a valid https Request (look `Context.IsSSL()`).
// Example: `map[string]string{"X-Forwarded-Proto": "https"}`.
//
// Defaults to empty map.
SSLProxyHeaders map[string]string `json:"sslProxyHeaders" yaml:"SSLProxyHeaders" toml:"SSLProxyHeaders"`
// HostProxyHeaders defines the set of headers that may hold a proxied hostname value for the clients.
// Look `Context.Host()` for more.
// Defaults to empty map.
HostProxyHeaders map[string]bool `json:"hostProxyHeaders" yaml:"HostProxyHeaders" toml:"HostProxyHeaders"`
// Other are the custom, dynamic options, can be empty.
// This field used only by you to set any app's options you want.
//
// Defaults to empty map.
Other map[string]interface{} `json:"other,omitempty" yaml:"Other" toml:"Other"`
}
```
### Load from [YAML](https://yaml.org/) ### Load from [YAML](https://yaml.org/)
Using the `iris.YAML("path")`. Using the `iris.YAML("path")`.
@ -88,173 +405,36 @@ configuration options without even a glitch to the documentation.
List of functional options: List of functional options:
```go ```go
// WithGlobalConfiguration will load the global yaml configuration file var (
// from the home directory and it will set/override the whole app's configuration WithGlobalConfiguration Configurator
// to that file's contents. The global configuration file can be modified by user WithoutStartupLog, WithoutBanner Configurator
// and be used by multiple iris instances. WithoutInterruptHandler Configurator
// WithoutPathCorrection Configurator
// This is useful when we run multiple iris servers that share the same WithPathIntelligence Configurator
// configuration, even with custom values at its "Other" field. WithoutPathCorrectionRedirection Configurator
// WithoutBodyConsumptionOnUnmarshal Configurator
// Usage: `app.Configure(iris.WithGlobalConfiguration)` or `app.Run([iris.Runner], iris.WithGlobalConfiguration)`. WithEmptyFormError Configurator
var WithGlobalConfiguration Configurator WithPathEscape Configurator
WithLowercaseRouting Configurator
WithOptimizations Configurator
WithFireMethodNotAllowed Configurator
WithoutAutoFireStatusCode Configurator
WithResetOnFireErrorCode Configurator
WithTunneling Configurator
)
// WithLogLevel sets the `Configuration.LogLevel` field.
func WithLogLevel(level string) Configurator func WithLogLevel(level string) Configurator
// WithoutServerError will cause to ignore the matched "errors"
// from the main application's `Run/Listen` function.
//
// Usage:
// err := app.Listen(":8080", iris.WithoutServerError(iris.ErrServerClosed))
// will return `nil` if the server's error was `http/iris#ErrServerClosed`.
//
// See `Configuration#IgnoreServerErrors []string` too.
//
// Example: https://github.com/kataras/iris/tree/master/_examples/http-server/listen-addr/omit-server-errors
func WithoutServerError(errors ...error) Configurator func WithoutServerError(errors ...error) Configurator
// WithoutStartupLog turns off the information send, once, to the terminal when the main server is open.
var WithoutStartupLog Configurator
// WithoutBanner is a conversion for the `WithoutStartupLog` option.
//
// Turns off the information send, once, to the terminal when the main server is open.
var WithoutBanner = WithoutStartupLog
// WithoutInterruptHandler disables the automatic graceful server shutdown
// when control/cmd+C pressed.
var WithoutInterruptHandler Configurator
// WithoutPathCorrection disables the PathCorrection setting.
//
// See `Configuration`.
var WithoutPathCorrection Configurator
// WithPathIntelligence enables the EnablePathIntelligence setting.
//
// See `Configuration`.
var WithPathIntelligence Configurator
// WithoutPathCorrectionRedirection disables the PathCorrectionRedirection setting.
//
// See `Configuration`.
var WithoutPathCorrectionRedirection Configurator
// WithoutBodyConsumptionOnUnmarshal disables BodyConsumptionOnUnmarshal setting.
//
// See `Configuration`.
var WithoutBodyConsumptionOnUnmarshal Configurator
// WithEmptyFormError enables the setting `FireEmptyFormError`.
//
// See `Configuration`.
var WithEmptyFormError Configurator
// WithoutAutoFireStatusCode disables the AutoFireStatusCode setting.
//
// See `Configuration`.
var WithoutAutoFireStatusCode Configurator
// WithPathEscape sets the EnablePathEscape setting to true.
//
// See `Configuration`.
var WithPathEscape Configurator
// WithLowercaseRouting enables for lowercase routing by
// setting the `ForceLowercaseRoutes` to true.
//
// See `Configuration`.
var WithLowercaseRouting Configurator
// WithOptimizations can force the application to optimize for the best performance where is possible.
//
// See `Configuration`.
var WithOptimizations Configurator
// WithFireMethodNotAllowed enables the FireMethodNotAllowed setting.
//
// See `Configuration`.
func WithFireMethodNotAllowed Configurator
// WithTimeFormat sets the TimeFormat setting.
//
// See `Configuration`.
func WithTimeFormat(timeformat string) Configurator func WithTimeFormat(timeformat string) Configurator
// WithCharset sets the Charset setting.
//
// See `Configuration`.
func WithCharset(charset string) Configurator func WithCharset(charset string) Configurator
// WithPostMaxMemory sets the maximum post data size
// that a client can send to the server, this differs
// from the overral request body size which can be modified
// by the `context#SetMaxRequestBodySize` or `iris#LimitRequestBodySize`.
//
// Defaults to 32MB or 32 << 20 or 32*iris.MB if you prefer.
func WithPostMaxMemory(limit int64) Configurator func WithPostMaxMemory(limit int64) Configurator
func WithRemoteAddrHeader(header ...string) Configurator
// WithRemoteAddrHeader enables or adds a new or existing request header name
// that can be used to validate the client's real IP.
//
// By-default no "X-" header is consired safe to be used for retrieving the
// client's IP address, because those headers can manually change by
// the client. But sometimes are useful e.g., when behind a proxy
// you want to enable the "X-Forwarded-For" or when cloudflare
// you want to enable the "CF-Connecting-IP", inneed you
// can allow the `ctx.RemoteAddr()` to use any header
// that the client may sent.
//
// Defaults to an empty map but an example usage is:
// WithRemoteAddrHeader("X-Forwarded-For")
//
// Look `context.RemoteAddr()` for more.
func WithRemoteAddrHeader(headerName string) Configurator
// WithoutRemoteAddrHeader disables an existing request header name
// that can be used to validate and parse the client's real IP.
//
//
// Keep note that RemoteAddrHeaders is already defaults to an empty map
// so you don't have to call this Configurator if you didn't
// add allowed headers via configuration or via `WithRemoteAddrHeader` before.
//
// Look `context.RemoteAddr()` for more.
func WithoutRemoteAddrHeader(headerName string) Configurator func WithoutRemoteAddrHeader(headerName string) Configurator
// WithRemoteAddrPrivateSubnet adds a new private sub-net to be excluded from `context.RemoteAddr`.
// See `WithRemoteAddrHeader` too.
func WithRemoteAddrPrivateSubnet(startIP, endIP string) Configurator func WithRemoteAddrPrivateSubnet(startIP, endIP string) Configurator
func WithSSLProxyHeader(headerKey, headerValue string) Configurator
// WithOtherValue adds a value based on a key to the Other setting. func WithHostProxyHeader(headers ...string) Configurator
//
// See `Configuration.Other`.
func WithOtherValue(key string, val interface{}) Configurator func WithOtherValue(key string, val interface{}) Configurator
// WithSitemap enables the sitemap generator.
// Use the Route's `SetLastMod`, `SetChangeFreq` and `SetPriority` to modify
// the sitemap's URL child element properties.
//
// It accepts a "startURL" input argument which
// is the prefix for the registered routes that will be included in the sitemap.
//
// If more than 50,000 static routes are registered then sitemaps will be splitted and a sitemap index will be served in
// /sitemap.xml.
//
// If `Application.I18n.Load/LoadAssets` is called then the sitemap will contain translated links for each static route.
//
// If the result does not complete your needs you can take control
// and use the github.com/kataras/sitemap package to generate a customized one instead.
//
// Example: https://github.com/kataras/iris/tree/master/_examples/sitemap.
func WithSitemap(startURL string) Configurator func WithSitemap(startURL string) Configurator
// WithTunneling is the `iris.Configurator` for the `iris.Configuration.Tunneling` field.
// It's used to enable http tunneling for an Iris Application, per registered host
//
// Alternatively use the `iris.WithConfiguration(iris.Configuration{Tunneling: iris.TunnelingConfiguration{ ...}}}`.
var WithTunneling Configuartor
``` ```
## Custom values ## Custom values

2
Content-negotiation.md

@ -15,7 +15,7 @@ Based on:
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding
Implemented on: Implemented on:
- https://github.com/kataras/iris/pull/1316/commits/8ee0de51c593fe0483fbea38117c3c88e065f2ef - https://github.com/kataras/iris/pull/1316/commits/8ee0de51c593fe0483fbea38117c3c88e065f2ef#diff-15cce7299aae8810bcab9b0bf9a2fdb1
--------- ---------

4
Installation.md

@ -17,10 +17,10 @@ Or edit your project's `go.mod` file.
```sh ```sh
module your_project_name module your_project_name
go 1.13 go 1.14
require ( require (
github.com/kataras/iris/v12 v12.1.8 github.com/kataras/iris/v12 v12.2.0
) )
``` ```

42
Routing-context-methods.md

@ -4,24 +4,6 @@ Here is a full list of methods that the `iris.Context` provides.
```go ```go
type Context interface { type Context interface {
// BeginRequest is executing once for each request
// it should prepare the (new or acquired from pool) context's fields for the new request.
// Do NOT call it manually. Framework calls it automatically.
//
// Resets
// 1. handlers to nil.
// 2. values to empty.
// 3. the defer function.
// 4. response writer to the http.ResponseWriter.
// 5. request to the *http.Request.
BeginRequest(http.ResponseWriter, *http.Request)
// EndRequest is executing once after a response to the request was sent and this context is useless or released.
// Do NOT call it manually. Framework calls it automatically.
//
// 1. executes the Defer function (if any).
// 2. flushes the response writer's result or fire any error handler.
// 3. releases the response writer.
EndRequest()
// Defer executes a handler on this Context right before the request ends. // Defer executes a handler on this Context right before the request ends.
// The `StopExecution` does not effect the execution of this defer handler. // The `StopExecution` does not effect the execution of this defer handler.
// The "h" runs before `FireErrorCode` (when response status code is not successful). // The "h" runs before `FireErrorCode` (when response status code is not successful).
@ -76,7 +58,6 @@ type Context interface {
SetHandlers(Handlers) SetHandlers(Handlers)
// Handlers keeps tracking of the current handlers. // Handlers keeps tracking of the current handlers.
Handlers() Handlers Handlers() Handlers
// HandlerIndex sets the current index of the // HandlerIndex sets the current index of the
// current context's handlers chain. // current context's handlers chain.
// If n < 0 or the current handlers length is 0 then it just returns the // If n < 0 or the current handlers length is 0 then it just returns the
@ -253,6 +234,7 @@ type Context interface {
// based on the 'escape'. // based on the 'escape'.
RequestPath(escape bool) string RequestPath(escape bool) string
// Host returns the host part of the current url. // Host returns the host part of the current url.
// This method makes use of the `Configuration.HostProxyHeaders` field too.
Host() string Host() string
// Subdomain returns the subdomain of this request, if any. // Subdomain returns the subdomain of this request, if any.
// Note that this is a fast method which does not cover all cases. // Note that this is a fast method which does not cover all cases.
@ -307,14 +289,19 @@ type Context interface {
IsMobile() bool IsMobile() bool
// IsScript reports whether a client is a script. // IsScript reports whether a client is a script.
IsScript() bool IsScript() bool
// IsSSL reports whether the client is running under HTTPS SSL.
//
// See `IsHTTP2` too.
IsSSL() bool
// IsHTTP2 reports whether the protocol version for incoming request was HTTP/2. // IsHTTP2 reports whether the protocol version for incoming request was HTTP/2.
// The client code always uses either HTTP/1.1 or HTTP/2. // The client code always uses either HTTP/1.1 or HTTP/2.
//
// See `IsSSL` too.
IsHTTP2() bool IsHTTP2() bool
// IsGRPC reports whether the request came from a gRPC client. // IsGRPC reports whether the request came from a gRPC client.
IsGRPC() bool IsGRPC() bool
// GetReferrer extracts and returns the information from the "Referrer" header as specified // GetReferrer extracts and returns the information from the "Referer" (or "Referrer") header
// in https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy // and url query parameter as specified in https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy.
// or by the URL query parameter "referrer".
GetReferrer() Referrer GetReferrer() Referrer
// SetLanguage force-sets the language for i18n, can be used inside a middleare. // SetLanguage force-sets the language for i18n, can be used inside a middleare.
// It has the highest priority over the rest and if it is empty then it is ignored, // It has the highest priority over the rest and if it is empty then it is ignored,
@ -574,9 +561,14 @@ type Context interface {
// is false (as defaulted) in this case the caller should check the pointer to // is false (as defaulted) in this case the caller should check the pointer to
// see if something was actually binded. // see if something was actually binded.
// //
// If a client sent an unknown field, this method will return an error,
// in order to ignore that error use the `err != nil && !iris.IsErrPath(err)`.
//
// Example: https://github.com/kataras/iris/blob/master/_examples/request-body/read-form/main.go // Example: https://github.com/kataras/iris/blob/master/_examples/request-body/read-form/main.go
ReadForm(formObject interface{}) error ReadForm(formObject interface{}) error
// ReadQuery binds url query to "ptr". The struct field tag is "url". // ReadQuery binds url query to "ptr". The struct field tag is "url".
// If a client sent an unknown field, this method will return an error,
// in order to ignore that error use the `err != nil && !iris.IsErrPath(err)`.
// //
// Example: https://github.com/kataras/iris/blob/master/_examples/request-body/read-query/main.go // Example: https://github.com/kataras/iris/blob/master/_examples/request-body/read-query/main.go
ReadQuery(ptr interface{}) error ReadQuery(ptr interface{}) error
@ -1060,13 +1052,13 @@ type Context interface {
// through APIContainer(app.ConfigureContainer) or MVC(mvc.New) // through APIContainer(app.ConfigureContainer) or MVC(mvc.New)
// in sake of minimum performance cost. // in sake of minimum performance cost.
// //
// See `UnRegisterDependency` too. // See `UnregisterDependency` too.
RegisterDependency(v interface{}) RegisterDependency(v interface{})
// UnRegisterDependency removes a dependency based on its type. // UnregisterDependency removes a dependency based on its type.
// Reports whether a dependency with that type was found and removed successfully. // Reports whether a dependency with that type was found and removed successfully.
// //
// See `RegisterDependency` too. // See `RegisterDependency` too.
UnRegisterDependency(typ reflect.Type) bool UnregisterDependency(typ reflect.Type) bool
// Application returns the iris app instance which belongs to this context. // Application returns the iris app instance which belongs to this context.
// Worth to notice that this function returns an interface // Worth to notice that this function returns an interface

16
Routing-middleware.md

@ -166,19 +166,3 @@ Here is a list of some handlers made specifically for Iris:
## Third-Party ## 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](https://github.com/kataras/iris/tree/master/_examples/convert-handlers). Iris has its own middleware form of `func(ctx iris.Context)` but it's also compatible with all `net/http` middleware forms. See [here](https://github.com/kataras/iris/tree/master/_examples/convert-handlers).
Here's a small list of useful third-party handlers:
| Middleware | Description |
| -----------|-------------|
| [goth](https://github.com/markbates/goth) | OAuth, OAuth2 authentication. [Example](https://github.com/kataras/iris/tree/master/_examples/auth/goth) |
| [permissions2](https://github.com/xyproto/permissions2) | Cookies, users and permissions. [Example](https://github.com/kataras/iris/tree/master/_examples/auth/permissions) |
| [csp](https://github.com/awakenetworks/csp) | [Content Security Policy](https://www.w3.org/TR/CSP2/) (CSP) support |
| [delay](https://github.com/jeffbmartinez/delay) | Add delays/latency to endpoints. Useful when testing effects of high latency |
| [onthefly](https://github.com/xyproto/onthefly) | Generate TinySVG, HTML and CSS on the fly |
| [RestGate](https://github.com/pjebs/restgate) | Secure authentication for REST API endpoints |
| [stats](https://github.com/thoas/stats) | Store information about your web application (response time, etc.) |
| [VanGoH](https://github.com/auroratechnologies/vangoh) | Configurable [AWS-Style](http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html) HMAC authentication middleware |
| [digits](https://github.com/bamarni/digits) | Middleware that handles [Twitter Digits](https://get.digits.com/) authentication |
> Feel free to put up your own middleware in this list!