kataras/iris
### [`v12.2.0-alpha3`](https://togithub.com/kataras/iris/blob/master/HISTORY.md#Next-currently-v1220-alpha3-)
[Compare Source](https://togithub.com/kataras/iris/compare/v12.2.0-alpha2...v12.2.0-alpha3)
### Next (currently v12.2.0-alpha3)
This release introduces new features and some breaking changes.
The codebase for Dependency Injection, Internationalization and localization and more have been simplified a lot (fewer LOCs and easier to read and follow up).
#### Fixes and Improvements
- Replace json-iterator with go-json as requested at [#1818](https://togithub.com/kataras/iris/issues/1818).
- New `iris.IsErrEmptyJSON(err) bool` which 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).
Example Code:
```go
func handler(ctx iris.Context) {
var opts SearchOptions
if err := ctx.ReadJSON(&opts); err != nil && !iris.IsErrEmptyJSON(err) {
ctx.StopWithJSON(iris.StatusBadRequest, iris.Map{"message": "unable to parse body"})
return
}
// [...continue with default values of "opts" struct if the client didn't provide some]
}
```
That means that the client can optionally set a JSON body.
- New `APIContainer.EnableStrictMode(bool)` to disable automatic payload binding and panic on missing dependencies for exported struct'sfields or function's input parameters on MVC controller or hero function or PartyConfigurator.
- New `Party.PartyConfigure(relativePath string, partyReg ...PartyConfigurator) Party` helper, registers a children Party like `Party` and `PartyFunc` but instead it accepts a structure value which may contain one or more of the dependencies registered by `RegisterDependency` or `ConfigureContainer().RegisterDependency` methods and fills the unset/zero exported struct's fields respectfully (useful when the api's dependencies amount are too much to pass on a function).
- **New feature:** add the ability to set custom error handlers on path type parameters errors (existing or custom ones). Example Code:
```go
app.Macros().Get("uuid").HandleError(func(ctx iris.Context, paramIndex int, err error) {
ctx.StatusCode(iris.StatusBadRequest)
param := ctx.Params().GetEntryAt(paramIndex)
ctx.JSON(iris.Map{
"error": err.Error(),
"message": "invalid path parameter",
"parameter": param.Key,
"value": param.ValueRaw,
})
})
app.Get("/users/{id:uuid}", getUser)
```
- Improve the performance and fix `:int, :int8, :int16, :int32, :int64, :uint, :uint8, :uint16, :uint32, :uint64` path type parameters couldn't accept a positive number written with the plus symbol or with a leading zeroes, e.g. `+42` and `021`.
- The `iris.WithEmptyFormError` option is respected on `context.ReadQuery` method too, as requested at [#1727](https://togithub.com/kataras/iris/issues/1727). [Example comments](https://togithub.com/kataras/iris/blob/master/\_examples/request-body/read-query/main.go) were updated.
- New `httptest.Strict` option setter to enable the `httpexpect.RequireReporter` instead of the default \`httpexpect.AssetReporter. Use that to enable complete test failure on the first error. As requested at: [#1722](https://togithub.com/kataras/iris/issues/1722).
- New `uuid` builtin path parameter type. Example:
```go
// +------------------------+
// | {param:uuid} |
// +------------------------+
// UUIDv4 (and v1) path parameter validation.
// http://localhost:8080/user/bb4f33e4-dc08-40d8-9f2b-e8b2bb615c0e -> OK
// http://localhost:8080/user/dsadsa-invalid-uuid -> NOT FOUND
app.Get("/user/{id:uuid}", func(ctx iris.Context) {
id := ctx.Params().Get("id")
ctx.WriteString(id)
})
```
- New `Configuration.KeepAlive` and `iris.WithKeepAlive(time.Duration) Configurator` added as helpers to start the server using a tcp listener featured with keep-alive.
- New `DirOptions.ShowHidden bool` is added by [@tuhao1020](https://togithub.com/tuhao1020) at [PR #1717](https://togithub.com/kataras/iris/pull/1717) to show or hide the hidden files when `ShowList` is set to true.
- New `Context.ReadJSONStream` method and `JSONReader` options for `Context.ReadJSON` and `Context.ReadJSONStream`, see the [example](\_examples/request-body/read-json-stream/main.go).
- New `FallbackView` feature, per-party or per handler chain. Example can be found at: [\_examples/view/fallback](\_examples/view/fallback).
```go
app.FallbackView(iris.FallbackViewFunc(func(ctx iris.Context, err iris.ErrViewNotExist) error {
// err.Name is the previous template name.
// err.IsLayout reports whether the failure came from the layout template.
// err.Data is the template data provided to the previous View call.
// [...custom logic e.g. ctx.View("fallback.html", err.Data)]
return err
}))
```
- New `versioning.Aliases` middleware and up to 80% faster version resolve. Example Code:
```go
app := iris.New()
api := app.Party("/api")
api.Use(Aliases(map[string]string{
versioning.Empty: "1", // when no version was provided by the client.
"beta": "4.0.0",
"stage": "5.0.0-alpha"
}))
v1 := NewGroup(api, ">=1.0.0 <2.0.0")
v1.Get/Post...
v4 := NewGroup(api, ">=4.0.0 <5.0.0")
v4.Get/Post...
stage := NewGroup(api, "5.0.0-alpha")
stage.Get/Post...
```
- New [Basic Authentication](https://togithub.com/kataras/iris/tree/master/middleware/basicauth) middleware. Its `Default` function has not changed, however, the rest, e.g. `New` contains breaking changes as the new middleware features new functionalities.
- Add `iris.DirOptions.SPA bool` field to allow [Single Page Applications](https://togithub.com/kataras/iris/tree/master/\_examples/file-server/single-page-application/basic/main.go) under a file server.
- A generic User interface, see the `Context.SetUser/User` methods in the New Context Methods section for more. In-short, the basicauth middleware's stored user can now be retrieved through `Context.User()` which provides more information than the native `ctx.Request().BasicAuth()` method one. Third-party authentication middleware creators can benefit of these two methods, plus the Logout below.
- A `Context.Logout` method is added, can be used to invalidate [basicauth](https://togithub.com/kataras/iris/blob/master/\_examples/auth/basicauth/basic/main.go) or [jwt](https://togithub.com/kataras/iris/blob/master/\_examples/auth/jwt/blocklist/main.go) client credentials.
- Add the ability to [share functions](https://togithub.com/kataras/iris/tree/master/\_examples/routing/writing-a-middleware/share-funcs) between handlers chain and add an [example](https://togithub.com/kataras/iris/tree/master/\_examples/routing/writing-a-middleware/share-services) on sharing Go structures (aka services).
- Add the new `Party.UseOnce` method to the `*Route`
- Add a new `*Route.RemoveHandler(...interface{}) int` and `Party.RemoveHandler(...interface{}) Party` methods, delete a handler based on its name or the handler pc function.
```go
func middleware(ctx iris.Context) {
// [...]
}
func main() {
app := iris.New()
// Register the middleware to all matched routes.
app.Use(middleware)
// Handlers = middleware, other
app.Get("/", index)
// Handlers = other
app.Get("/other", other).RemoveHandler(middleware)
}
```
- Redis Driver is now based on the [go-redis](https://togithub.com/go-redis/redis/) module. Radix and redigo removed entirely. Sessions are now stored in hashes which fixes [issue #1610](https://togithub.com/kataras/iris/issues/1610). The only breaking change on default configuration is that the `redis.Config.Delim` option was removed. The redis sessions database driver is now defaults to the `&redis.GoRedisDriver{}`. End-developers can implement their own implementations too. The `Database#Close` is now automatically called on interrupt signals, no need to register it by yourself.
- Add builtin support for **[i18n pluralization](https://togithub.com/kataras/iris/tree/master/\_examples/i18n/plurals)**. Please check out the [following yaml locale example](https://togithub.com/kataras/iris/tree/master/\_examples/i18n/plurals/locales/en-US/welcome.yml) to see an overview of the supported formats.
- Fix [#1650](https://togithub.com/kataras/iris/issues/1650)
- Fix [#1649](https://togithub.com/kataras/iris/issues/1649)
- Fix [#1648](https://togithub.com/kataras/iris/issues/1648)
- Fix [#1641](https://togithub.com/kataras/iris/issues/1641)
- Add `Party.SetRoutesNoLog(disable bool) Party` to disable (the new) verbose logging of next routes.
- Add `mvc.Application.SetControllersNoLog(disable bool) *mvc.Application` to disable (the new) verbose logging of next controllers. As requested at [#1630](https://togithub.com/kataras/iris/issues/1630).
- Fix [#1621](https://togithub.com/kataras/iris/issues/1621) and add a new `cache.WithKey` to customize the cached entry key.
- Add a `Response() *http.Response` to the Response Recorder.
- Fix Response Recorder `Flush` when transfer-encoding is `chunked`.
- Fix Response Recorder `Clone` concurrent access afterwards.
- Add a `ParseTemplate` method on view engines to manually parse and add a template from a text as [requested](https://togithub.com/kataras/iris/issues/1617). [Examples](https://togithub.com/kataras/iris/tree/master/\_examples/view/parse-template).
- Full `http.FileSystem` interface support for all **view** engines as [requested](https://togithub.com/kataras/iris/issues/1575). The first argument of the functions(`HTML`, `Blocks`, `Pug`, `Amber`, `Ace`, `Jet`, `Django`, `Handlebars`) can now be either a directory of `string` type (like before) or a value which completes the `http.FileSystem` interface. The `.Binary` method of all view engines was removed: pass the go-bindata's latest version `AssetFile()` exported function as the first argument instead of string.
- Add `Route.ExcludeSitemap() *Route` to exclude a route from sitemap as requested in [chat](https://chat.iris-go.com), also offline routes are excluded automatically now.
- Improved tracing (with `app.Logger().SetLevel("debug")`) for routes. Screens:
##### DBUG Routes (1)
##### DBUG Routes (2)
##### DBUG Routes (3)
- Update the [pprof middleware](https://togithub.com/kataras/iris/tree/master/middleware/pprof).
- New `Controller.HandleHTTPError(mvc.Code) ` optional Controller method to handle http errors as requested at: [MVC - More Elegent OnErrorCode registration?](https://togithub.com/kataras/iris/issues/1595). Example can be found [here](https://togithub.com/kataras/iris/tree/master/\_examples/mvc/error-handler-http/main.go).
- New [Rewrite Engine Middleware](https://togithub.com/kataras/iris/tree/master/middleware/rewrite). Set up redirection rules for path patterns using the syntax we all know. [Example Code](https://togithub.com/kataras/iris/tree/master/\_examples/routing/rewrite).
```yml
RedirectMatch: # REDIRECT_CODE_DIGITS | PATTERN_REGEX | TARGET_REPL
```
Configuration
📅 Schedule: At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
[ ] If you want to rebase/retry this PR, check this box.
This PR contains the following updates:
v12.2.0-alpha2->v12.2.0-alpha3Release Notes
kataras/iris
### [`v12.2.0-alpha3`](https://togithub.com/kataras/iris/blob/master/HISTORY.md#Next-currently-v1220-alpha3-) [Compare Source](https://togithub.com/kataras/iris/compare/v12.2.0-alpha2...v12.2.0-alpha3) ### Next (currently v12.2.0-alpha3) This release introduces new features and some breaking changes. The codebase for Dependency Injection, Internationalization and localization and more have been simplified a lot (fewer LOCs and easier to read and follow up). #### Fixes and Improvements - Replace json-iterator with go-json as requested at [#1818](https://togithub.com/kataras/iris/issues/1818). - New `iris.IsErrEmptyJSON(err) bool` which 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). Example Code: ```go func handler(ctx iris.Context) { var opts SearchOptions if err := ctx.ReadJSON(&opts); err != nil && !iris.IsErrEmptyJSON(err) { ctx.StopWithJSON(iris.StatusBadRequest, iris.Map{"message": "unable to parse body"}) return } // [...continue with default values of "opts" struct if the client didn't provide some] } ``` That means that the client can optionally set a JSON body. - New `APIContainer.EnableStrictMode(bool)` to disable automatic payload binding and panic on missing dependencies for exported struct'sfields or function's input parameters on MVC controller or hero function or PartyConfigurator. - New `Party.PartyConfigure(relativePath string, partyReg ...PartyConfigurator) Party` helper, registers a children Party like `Party` and `PartyFunc` but instead it accepts a structure value which may contain one or more of the dependencies registered by `RegisterDependency` or `ConfigureContainer().RegisterDependency` methods and fills the unset/zero exported struct's fields respectfully (useful when the api's dependencies amount are too much to pass on a function). - **New feature:** add the ability to set custom error handlers on path type parameters errors (existing or custom ones). Example Code: ```go app.Macros().Get("uuid").HandleError(func(ctx iris.Context, paramIndex int, err error) { ctx.StatusCode(iris.StatusBadRequest) param := ctx.Params().GetEntryAt(paramIndex) ctx.JSON(iris.Map{ "error": err.Error(), "message": "invalid path parameter", "parameter": param.Key, "value": param.ValueRaw, }) }) app.Get("/users/{id:uuid}", getUser) ``` - Improve the performance and fix `:int, :int8, :int16, :int32, :int64, :uint, :uint8, :uint16, :uint32, :uint64` path type parameters couldn't accept a positive number written with the plus symbol or with a leading zeroes, e.g. `+42` and `021`. - The `iris.WithEmptyFormError` option is respected on `context.ReadQuery` method too, as requested at [#1727](https://togithub.com/kataras/iris/issues/1727). [Example comments](https://togithub.com/kataras/iris/blob/master/\_examples/request-body/read-query/main.go) were updated. - New `httptest.Strict` option setter to enable the `httpexpect.RequireReporter` instead of the default \`httpexpect.AssetReporter. Use that to enable complete test failure on the first error. As requested at: [#1722](https://togithub.com/kataras/iris/issues/1722). - New `uuid` builtin path parameter type. Example: ```go // +------------------------+ // | {param:uuid} | // +------------------------+ // UUIDv4 (and v1) path parameter validation. // http://localhost:8080/user/bb4f33e4-dc08-40d8-9f2b-e8b2bb615c0e -> OK // http://localhost:8080/user/dsadsa-invalid-uuid -> NOT FOUND app.Get("/user/{id:uuid}", func(ctx iris.Context) { id := ctx.Params().Get("id") ctx.WriteString(id) }) ``` - New `Configuration.KeepAlive` and `iris.WithKeepAlive(time.Duration) Configurator` added as helpers to start the server using a tcp listener featured with keep-alive. - New `DirOptions.ShowHidden bool` is added by [@tuhao1020](https://togithub.com/tuhao1020) at [PR #1717](https://togithub.com/kataras/iris/pull/1717) to show or hide the hidden files when `ShowList` is set to true. - New `Context.ReadJSONStream` method and `JSONReader` options for `Context.ReadJSON` and `Context.ReadJSONStream`, see the [example](\_examples/request-body/read-json-stream/main.go). - New `FallbackView` feature, per-party or per handler chain. Example can be found at: [\_examples/view/fallback](\_examples/view/fallback). ```go app.FallbackView(iris.FallbackViewFunc(func(ctx iris.Context, err iris.ErrViewNotExist) error { // err.Name is the previous template name. // err.IsLayout reports whether the failure came from the layout template. // err.Data is the template data provided to the previous View call. // [...custom logic e.g. ctx.View("fallback.html", err.Data)] return err })) ``` - New `versioning.Aliases` middleware and up to 80% faster version resolve. Example Code: ```go app := iris.New() api := app.Party("/api") api.Use(Aliases(map[string]string{ versioning.Empty: "1", // when no version was provided by the client. "beta": "4.0.0", "stage": "5.0.0-alpha" })) v1 := NewGroup(api, ">=1.0.0 <2.0.0") v1.Get/Post... v4 := NewGroup(api, ">=4.0.0 <5.0.0") v4.Get/Post... stage := NewGroup(api, "5.0.0-alpha") stage.Get/Post... ``` - New [Basic Authentication](https://togithub.com/kataras/iris/tree/master/middleware/basicauth) middleware. Its `Default` function has not changed, however, the rest, e.g. `New` contains breaking changes as the new middleware features new functionalities. - Add `iris.DirOptions.SPA bool` field to allow [Single Page Applications](https://togithub.com/kataras/iris/tree/master/\_examples/file-server/single-page-application/basic/main.go) under a file server. - A generic User interface, see the `Context.SetUser/User` methods in the New Context Methods section for more. In-short, the basicauth middleware's stored user can now be retrieved through `Context.User()` which provides more information than the native `ctx.Request().BasicAuth()` method one. Third-party authentication middleware creators can benefit of these two methods, plus the Logout below. - A `Context.Logout` method is added, can be used to invalidate [basicauth](https://togithub.com/kataras/iris/blob/master/\_examples/auth/basicauth/basic/main.go) or [jwt](https://togithub.com/kataras/iris/blob/master/\_examples/auth/jwt/blocklist/main.go) client credentials. - Add the ability to [share functions](https://togithub.com/kataras/iris/tree/master/\_examples/routing/writing-a-middleware/share-funcs) between handlers chain and add an [example](https://togithub.com/kataras/iris/tree/master/\_examples/routing/writing-a-middleware/share-services) on sharing Go structures (aka services). - Add the new `Party.UseOnce` method to the `*Route` - Add a new `*Route.RemoveHandler(...interface{}) int` and `Party.RemoveHandler(...interface{}) Party` methods, delete a handler based on its name or the handler pc function. ```go func middleware(ctx iris.Context) { // [...] } func main() { app := iris.New() // Register the middleware to all matched routes. app.Use(middleware) // Handlers = middleware, other app.Get("/", index) // Handlers = other app.Get("/other", other).RemoveHandler(middleware) } ``` - Redis Driver is now based on the [go-redis](https://togithub.com/go-redis/redis/) module. Radix and redigo removed entirely. Sessions are now stored in hashes which fixes [issue #1610](https://togithub.com/kataras/iris/issues/1610). The only breaking change on default configuration is that the `redis.Config.Delim` option was removed. The redis sessions database driver is now defaults to the `&redis.GoRedisDriver{}`. End-developers can implement their own implementations too. The `Database#Close` is now automatically called on interrupt signals, no need to register it by yourself. - Add builtin support for **[i18n pluralization](https://togithub.com/kataras/iris/tree/master/\_examples/i18n/plurals)**. Please check out the [following yaml locale example](https://togithub.com/kataras/iris/tree/master/\_examples/i18n/plurals/locales/en-US/welcome.yml) to see an overview of the supported formats. - Fix [#1650](https://togithub.com/kataras/iris/issues/1650) - Fix [#1649](https://togithub.com/kataras/iris/issues/1649) - Fix [#1648](https://togithub.com/kataras/iris/issues/1648) - Fix [#1641](https://togithub.com/kataras/iris/issues/1641) - Add `Party.SetRoutesNoLog(disable bool) Party` to disable (the new) verbose logging of next routes. - Add `mvc.Application.SetControllersNoLog(disable bool) *mvc.Application` to disable (the new) verbose logging of next controllers. As requested at [#1630](https://togithub.com/kataras/iris/issues/1630). - Fix [#1621](https://togithub.com/kataras/iris/issues/1621) and add a new `cache.WithKey` to customize the cached entry key. - Add a `Response() *http.Response` to the Response Recorder. - Fix Response Recorder `Flush` when transfer-encoding is `chunked`. - Fix Response Recorder `Clone` concurrent access afterwards. - Add a `ParseTemplate` method on view engines to manually parse and add a template from a text as [requested](https://togithub.com/kataras/iris/issues/1617). [Examples](https://togithub.com/kataras/iris/tree/master/\_examples/view/parse-template). - Full `http.FileSystem` interface support for all **view** engines as [requested](https://togithub.com/kataras/iris/issues/1575). The first argument of the functions(`HTML`, `Blocks`, `Pug`, `Amber`, `Ace`, `Jet`, `Django`, `Handlebars`) can now be either a directory of `string` type (like before) or a value which completes the `http.FileSystem` interface. The `.Binary` method of all view engines was removed: pass the go-bindata's latest version `AssetFile()` exported function as the first argument instead of string. - Add `Route.ExcludeSitemap() *Route` to exclude a route from sitemap as requested in [chat](https://chat.iris-go.com), also offline routes are excluded automatically now. - Improved tracing (with `app.Logger().SetLevel("debug")`) for routes. Screens: ##### DBUG Routes (1)  ##### DBUG Routes (2)  ##### DBUG Routes (3)  - Update the [pprof middleware](https://togithub.com/kataras/iris/tree/master/middleware/pprof). - New `Controller.HandleHTTPError(mvc.Code)Configuration
📅 Schedule: At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR has been generated by WhiteSource Renovate. View repository job log here.