various improvements and new 'UseOnce' method - read HISTORY.md

Author: kataras

HISTORY.md

@@ -359,6 +359,10 @@ Response:
 
 Other Improvements:
 
+- `*versioning.Group` type is a full `Party` now.
+
+- `Party.UseOnce` - either inserts a middleware, or on the basis of the middleware already existing, replace that existing middleware instead.
+
 - Ability to register a view engine per group of routes or for the current chain of handlers through `Party.RegisterView` and `Context.ViewEngine` respectfully.
 
 - Add [Blocks](_examples/view/template_blocks_0) template engine. <!-- Reminder for @kataras: follow https://github.com/flosch/pongo2/pull/236#issuecomment-668950566 discussion so we can get back on using the original pongo2 repository as they fixed the issue about an incompatible 3rd party package (although they need more fixes, that's why I commented there) -->
@@ -527,6 +531,8 @@ New Context Methods:
 
 Breaking Changes:
 
+- `versioning.NewGroup(string)` now accepts a `Party` as its first input argument: `NewGroup(Party, string)`.
+- `versioning.RegisterGroups` is **removed** as it is no longer necessary.
 - `Configuration.RemoteAddrHeaders` from `map[string]bool` to `[]string`. If you used `With(out)RemoteAddrHeader` then you are ready to proceed without any code changes for that one.
 - `ctx.Gzip(boolean)` replaced with `ctx.CompressWriter(boolean) error`.
 - `ctx.GzipReader(boolean) error` replaced with `ctx.CompressReader(boolean) error`.

_examples/README.md

@@ -101,6 +101,7 @@
     * [The `urlpath` tmpl func](view/template_html_3/main.go)
     * [The `url` tmpl func](view/template_html_4/main.go)
     * [Inject Data Between Handlers](view/context-view-data/main.go)
+    * [Inject Engine Between Handlers](view/context-view-engine/main.go)
     * [Embedding Templates Into App Executable File](view/embedding-templates-into-app/main.go)
     * [Write to a custom `io.Writer`](view/write-to)
     * [Blocks](view/template_blocks_0)

_examples/mvc/versioned-controller/main.go

@@ -31,7 +31,7 @@ func newApp() *iris.Application {
 		m.Handle(new(v1Controller), mvc.Version("1"), mvc.Deprecated(opts)) // 1 or 1.0, 1.0.0 ...
 		m.Handle(new(v2Controller), mvc.Version("2.3"))                     // 2.3 or 2.3.0
 		m.Handle(new(v3Controller), mvc.Version(">=3, <4"))                 // 3, 3.x, 3.x.x ...
-		m.Handle(new(noVersionController))
+		m.Handle(new(noVersionController))                                  // or if missing it will respond with 501 version not found.
 	}
 
 	return app

_examples/routing/versioning/main.go

@@ -42,9 +42,16 @@ func examplePerRoute(app *iris.Application) {
 // Headers[1] = Accept-Version: "2"
 func examplePerParty(app *iris.Application) {
 	usersAPI := app.Party("/api/users")
+	// You can customize the way a version is extracting
+	// via middleware, for example:
+	// version url parameter, and, if it's missing we default it to "1".
+	usersAPI.Use(func(ctx iris.Context) {
+		versioning.SetVersion(ctx, ctx.URLParamDefault("version", "1"))
+		ctx.Next()
+	})
 
 	// version 1.
-	usersAPIV1 := versioning.NewGroup(">= 1, < 2")
+	usersAPIV1 := versioning.NewGroup(usersAPI, ">= 1, < 2")
 	usersAPIV1.Get("/", func(ctx iris.Context) {
 		ctx.Writef("v1 resource: /api/users handler")
 	})
@@ -53,15 +60,13 @@ func examplePerParty(app *iris.Application) {
 	})
 
 	// version 2.
-	usersAPIV2 := versioning.NewGroup(">= 2, < 3")
+	usersAPIV2 := versioning.NewGroup(usersAPI, ">= 2, < 3")
 	usersAPIV2.Get("/", func(ctx iris.Context) {
 		ctx.Writef("v2 resource: /api/users handler")
 	})
 	usersAPIV2.Post("/", func(ctx iris.Context) {
 		ctx.Writef("v2 resource: /api/users post handler")
 	})
-
-	versioning.RegisterGroups(usersAPI, versioning.NotFoundHandler, usersAPIV1, usersAPIV2)
 }
 
 func catsVersionExactly1Handler(ctx iris.Context) {

context/context.go

@@ -303,7 +303,7 @@ var acquireGoroutines = func() interface{} {
 }
 
 func (ctx *Context) Go(fn func(cancelCtx stdContext.Context)) (running int) {
-	g := ctx.Values().GetOrSet(goroutinesContextKey, acquireGoroutines).(*goroutines)
+	g := ctx.values.GetOrSet(goroutinesContextKey, acquireGoroutines).(*goroutines)
 	if fn != nil {
 		g.wg.Add(1)
 
@@ -613,6 +613,18 @@ func (ctx *Context) StopWithError(statusCode int, err error) {
 	ctx.StopWithText(statusCode, err.Error())
 }
 
+// StopWithPlainError like `StopWithError` but it does NOT
+// write anything to the response writer, it stores the error
+// so any error handler matching the given "statusCode" can handle it by its own.
+func (ctx *Context) StopWithPlainError(statusCode int, err error) {
+	if err == nil {
+		return
+	}
+
+	ctx.SetErr(err)
+	ctx.StopWithStatus(statusCode)
+}
+
 // StopWithJSON stops the handlers chain, writes the status code
 // and sends a JSON response.
 //
@@ -4459,7 +4471,7 @@ func (ctx *Context) Exec(method string, path string) {
 	// backup the request path information
 	backupPath := req.URL.Path
 	backupMethod := req.Method
-	// don't backupValues := ctx.Values().ReadOnly()
+	// don't backupValues := ctx.values.ReadOnly()
 	// set the request to be align with the 'againstRequestPath'
 	req.RequestURI = path
 	req.URL.Path = path
@@ -4548,7 +4560,7 @@ func (ctx *Context) RegisterDependency(v interface{}) {
 		val = reflect.ValueOf(v)
 	}
 
-	cv := ctx.Values().Get(DependenciesContextKey)
+	cv := ctx.values.Get(DependenciesContextKey)
 	if cv != nil {
 		m, ok := cv.(DependenciesMap)
 		if !ok {
@@ -4559,15 +4571,15 @@ func (ctx *Context) RegisterDependency(v interface{}) {
 		return
 	}
 
-	ctx.Values().Set(DependenciesContextKey, DependenciesMap{
+	ctx.values.Set(DependenciesContextKey, DependenciesMap{
 		val.Type(): val,
 	})
 }
 
 // UnregisterDependency removes a dependency based on its type.
 // Reports whether a dependency with that type was found and removed successfully.
 func (ctx *Context) UnregisterDependency(typ reflect.Type) bool {
-	cv := ctx.Values().Get(DependenciesContextKey)
+	cv := ctx.values.Get(DependenciesContextKey)
 	if cv != nil {
 		m, ok := cv.(DependenciesMap)
 		if ok {
@@ -4594,18 +4606,25 @@ const errorContextKey = "iris.context.error"
 // as a context value, it does nothing more.
 // Also, by-default this error's value is written to the client
 // on failures when no registered error handler is available (see `Party.On(Any)ErrorCode`).
-// See `GetError` to retrieve it back.
+// See `GetErr` to retrieve it back.
+//
+// To remove an error simply pass nil.
 //
 // Note that, if you want to stop the chain
-// with an error see the `StopWithError` instead.
+// with an error see the `StopWithError/StopWithPlainError` instead.
 func (ctx *Context) SetErr(err error) {
-	ctx.Values().Set(errorContextKey, err)
+	if err == nil {
+		ctx.values.Remove(errorContextKey)
+		return
+	}
+
+	ctx.values.Set(errorContextKey, err)
 }
 
 // GetErr is a helper which retrieves
 // the error value stored by `SetErr`.
 func (ctx *Context) GetErr() error {
-	if v := ctx.Values().Get(errorContextKey); v != nil {
+	if v := ctx.values.Get(errorContextKey); v != nil {
 		if err, ok := v.(error); ok {
 			return err
 		}

core/router/api_builder.go

@@ -138,6 +138,8 @@ func overlapRoute(r *Route, next *Route) {
 			return
 		}
 
+		ctx.SetErr(nil) // clear any stored error.
+		// Set the route to the next one and execute it.
 		ctx.SetCurrentRoute(next.ReadOnly)
 		ctx.HandlerIndex(0)
 		ctx.Do(nextHandlers)
@@ -768,6 +770,25 @@ func (api *APIBuilder) Use(handlers ...context.Handler) {
 	api.middleware = append(api.middleware, handlers...)
 }
 
+// UseOnce either inserts a middleware,
+// or on the basis of the middleware already existing,
+// replace that existing middleware instead.
+func (api *APIBuilder) UseOnce(handlers ...context.Handler) {
+reg:
+	for _, handler := range handlers {
+		name := context.HandlerName(handler)
+		for i, registeredHandler := range api.middleware {
+			registeredName := context.HandlerName(registeredHandler)
+			if name == registeredName {
+				api.middleware[i] = handler // replace this handler with the new one.
+				continue reg                // break and continue to the next handler.
+			}
+		}
+
+		api.middleware = append(api.middleware, handler) // or just insert it.
+	}
+}
+
 // UseGlobal registers handlers that should run at the very beginning.
 // It prepends those handler(s) to all routes,
 // including all parties, subdomains.

core/router/fs.go

@@ -46,7 +46,7 @@ type Attachments struct {
 type DirCacheOptions struct {
 	// Enable or disable cache.
 	Enable bool
-	// Minimium content size for compression in bytes.
+	// Minimum content size for compression in bytes.
 	CompressMinSize int64
 	// Ignore compress files that match this pattern.
 	CompressIgnore *regexp.Regexp

core/router/party.go

@@ -76,9 +76,14 @@ type Party interface {
 	// Use appends Handler(s) to the current Party's routes and child routes.
 	// If the current Party is the root, then it registers the middleware to all child Parties' routes too.
 	Use(middleware ...context.Handler)
+	// UseOnce either inserts a middleware,
+	// or on the basis of the middleware already existing,
+	// replace that existing middleware instead.
+	UseOnce(handlers ...context.Handler)
 	// Done appends to the very end, Handler(s) to the current Party's routes and child routes.
 	// The difference from .Use is that this/or these Handler(s) are being always running last.
 	Done(handlers ...context.Handler)
+
 	// Reset removes all the begin and done handlers that may derived from the parent party via `Use` & `Done`,
 	// and the execution rules.
 	// Note that the `Reset` will not reset the handlers that are registered via `UseGlobal` & `DoneGlobal`.

mvc/versioning.go

@@ -25,15 +25,8 @@ import (
 func Version(version string) OptionFunc {
 	return func(c *ControllerActivator) {
 		c.Router().SetRegisterRule(router.RouteOverlap) // required for this feature.
-
-		c.Use(func(ctx *context.Context) {
-			if !versioning.Match(ctx, version) {
-				ctx.StopExecution()
-				return
-			}
-
-			ctx.Next()
-		})
+		// Note: Do not use a group, we need c.Use for the specific controller's routes.
+		c.Use(versioning.Handler(version))
 	}
 }