Add iris#ConfigureHost as an alternative way to interact with the app's hosts.

Former-commit-id: 5f36f44b86b70818c4c0c6ef7c178b550cc4ac46

HISTORY.md

@@ -18,6 +18,64 @@ Developers are not forced to upgrade if they don't really need it. Upgrade whene
 
 **How to upgrade**: Open your command-line and execute this command: `go get -u github.com/kataras/iris`.
 
+# Mo, 31 July 2017 | v8.1.2
+
+Add a `ConfigureHost` function as an alternative way to customize the hosts via `host.Configurator`.
+The first way was to pass `host.Configurator` as optional arguments on `iris.Runner`s built'n functions (`iris#Server, iris#Listener, iris#Addr, iris#TLS, iris#AutoTLS`), example of this can be found [there](https://github.com/kataras/iris/blob/master/_examples/http-listening/notify-on-shutdown).
+
+Example Code:
+
+```go
+package main
+
+import (
+	stdContext "context"
+	"time"
+
+	"github.com/kataras/iris"
+	"github.com/kataras/iris/context"
+	"github.com/kataras/iris/core/host"
+)
+
+func main() {
+	app := iris.New()
+
+	app.Get("/", func(ctx context.Context) {
+		ctx.HTML("<h1>Hello, try to refresh the page after ~10 secs</h1>")
+	})
+
+    app.ConfigureHost(configureHost) // or pass "configureHost" as `app.Addr` argument, same result.
+
+	app.Logger().Info("Wait 10 seconds and check your terminal again")
+	// simulate a shutdown action here...
+	go func() {
+		<-time.After(10 * time.Second)
+		timeout := 5 * time.Second
+		ctx, cancel := stdContext.WithTimeout(stdContext.Background(), timeout)
+		defer cancel()
+		// close all hosts, this will notify the callback we had register
+		// inside the `configureHost` func.
+		app.Shutdown(ctx)
+	}()
+
+	// http://localhost:8080
+	// wait 10 seconds and check your terminal.
+	app.Run(iris.Addr(":8080"), iris.WithoutServerError(iris.ErrServerClosed))
+}
+
+func configureHost(su *host.Supervisor) {
+	// here we have full access to the host that will be created
+	// inside the `app.Run` or `app.NewHost` function .
+	//
+	// we're registering a shutdown "event" callback here:
+	su.RegisterOnShutdown(func() {
+		println("server is closed")
+	})
+	// su.RegisterOnError
+	// su.RegisterOnServe
+}
+```
+
 # Su, 30 July 2017
 
 Greetings my friends, nothing special today, no version number yet.

README.md

@@ -20,7 +20,7 @@ Iris is a fast, simple and efficient micro web framework for Go. It provides a b
 ### 📑 Table of contents
 
 * [Installation](#-installation)
-* [Latest changes](https://github.com/kataras/iris/blob/master/HISTORY.md#sa-29-july-2017--v811)
+* [Latest changes](https://github.com/kataras/iris/blob/master/HISTORY.md#mo-31-july-2017--v812)
 * [Learn](#-learn)
 	* [HTTP Listening](_examples/#http-listening)
 	* [Configuration](_examples/#configuration)
@@ -343,7 +343,7 @@ Thank You for your trust!
 
 ### 📌 Version
 
-Current: **8.1.1**
+Current: **8.1.2**
 
 Each new release is pushed to the master. It stays there until the next version. When a next version is released then the previous version goes to its own branch with `gopkg.in` as its import path (and its own vendor folder), in order to keep it working "for-ever".
 

_examples/http-listening/iris-configurator-and-host-configurator/README.md

@@ -0,0 +1,2 @@
+A silly example for this issue: https://github.com/kataras/iris/issues/688#issuecomment-318828259.
+However it seems useful and therefore is being included in the examples for everyone else.

_examples/http-listening/iris-configurator-and-host-configurator/counter/configurator.go

@@ -0,0 +1,32 @@
+package counter
+
+import (
+	"time"
+
+	"github.com/kataras/iris"
+	"github.com/kataras/iris/context"
+	"github.com/kataras/iris/core/host"
+)
+
+func Configurator(app *iris.Application) {
+	counterValue := 0
+
+	go func() {
+		ticker := time.NewTicker(time.Second)
+
+		for range ticker.C {
+			counterValue++
+		}
+
+		app.ConfigureHost(func(h *host.Supervisor) { // <- HERE: IMPORTANT
+			h.RegisterOnShutdown(func() {
+				ticker.Stop()
+			})
+		}) // or put the ticker outside of the gofunc and put the configurator before or after the app.Get, outside of this gofunc
+	}()
+
+	app.Get("/counter", func(ctx context.Context) {
+		ctx.Header("Content-Type", "text/plain")
+		ctx.Writef("Counter value = %d", counterValue)
+	})
+}

_examples/http-listening/iris-configurator-and-host-configurator/main.go

@@ -0,0 +1,14 @@
+package main
+
+import (
+	"github.com/kataras/iris/_examples/http-listening/iris-configurator-and-host-configurator/counter"
+
+	"github.com/kataras/iris"
+)
+
+func main() {
+	app := iris.New()
+	app.Configure(counter.Configurator)
+
+	app.Run(iris.Addr(":8080"))
+}

_examples/http-listening/notify-on-shutdown/main.go

@@ -16,6 +16,8 @@ func main() {
 		ctx.HTML("<h1>Hello, try to refresh the page after ~10 secs</h1>")
 	})
 
+	// app.ConfigureHost(configureHost) -> or pass "configureHost" as `app.Addr` argument, same result.
+
 	app.Logger().Info("Wait 10 seconds and check your terminal again")
 	// simulate a shutdown action here...
 	go func() {
@@ -40,9 +42,9 @@ func main() {
 
 func configureHost(su *host.Supervisor) {
 	// here we have full access to the host that will be created
-	// inside the `Run` function.
+	// inside the `app.Run` function or `NewHost`.
 	//
-	// we register a shutdown "event" callback
+	// we're registering a shutdown "event" callback here:
 	su.RegisterOnShutdown(func() {
 		println("server is closed")
 	})

doc.go

@@ -35,7 +35,7 @@ Source code and other details for the project are available at GitHub:
 
 Current Version
 
-8.1.1
+8.1.2
 
 Installation
 

iris.go

@@ -33,7 +33,7 @@ import (
 const (
 
 	// Version is the current version number of the Iris Web Framework.
-	Version = "8.1.1"
+	Version = "8.1.2"
 )
 
 // HTTP status codes as registered with IANA.
@@ -154,7 +154,8 @@ type Application struct {
 	// Additional Host Supervisors can be added to that list by calling the `app.NewHost` manually.
 	//
 	// Hosts field is available after `Run` or `NewHost`.
-	Hosts []*host.Supervisor
+	Hosts             []*host.Supervisor
+	hostConfigurators []host.Configurator
 }
 
 // New creates and returns a fresh empty iris *Application instance.
@@ -313,6 +314,28 @@ func (app *Application) SPA(assetHandler context.Handler) {
 	app.Router.WrapRouter(wrapper)
 }
 
+// ConfigureHost accepts one or more `host#Configuration`, these configurators functions
+// can access the host created by `app.Run`,
+// they're being executed when application is ready to being served to the public.
+//
+// It's an alternative way to interact with a host that is automatically created by
+// `app.Run`.
+//
+// These "configurators" can work side-by-side with the `iris#Addr, iris#Server, iris#TLS, iris#AutoTLS, iris#Listener`
+// final arguments("hostConfigs") too.
+//
+// Note that these application's host "configurators" will be shared with the rest of
+// the hosts that this app will may create (using `app.NewHost`), meaning that
+// `app.NewHost` will execute these "configurators" everytime that is being called as well.
+//
+// These "configurators" should be registered before the `app.Run` or `host.Serve/Listen` functions.
+func (app *Application) ConfigureHost(configurators ...host.Configurator) *Application {
+	app.mu.Lock()
+	app.hostConfigurators = append(app.hostConfigurators, configurators...)
+	app.mu.Unlock()
+	return app
+}
+
 // NewHost accepts a standar *http.Server object,
 // completes the necessary missing parts of that "srv"
 // and returns a new, ready-to-use, host (supervisor).
@@ -362,6 +385,8 @@ func (app *Application) NewHost(srv *http.Server) *host.Supervisor {
 
 	su.IgnoredErrors = append(su.IgnoredErrors, app.config.IgnoreServerErrors...)
 
+	su.Configure(app.hostConfigurators...)
+
 	app.Hosts = append(app.Hosts, su)
 
 	return su
@@ -404,6 +429,7 @@ type Runner func(*Application) error
 // i.e to add events for shutdown, serve or error.
 // An example of this use case can be found at:
 // https://github.com/kataras/iris/blob/master/_examples/http-listening/notify-on-shutdown/main.go
+// Look at the `ConfigureHost` too.
 //
 // See `Run` for more.
 func Listener(l net.Listener, hostConfigs ...host.Configurator) Runner {
@@ -425,6 +451,7 @@ func Listener(l net.Listener, hostConfigs ...host.Configurator) Runner {
 // i.e to add events for shutdown, serve or error.
 // An example of this use case can be found at:
 // https://github.com/kataras/iris/blob/master/_examples/http-listening/notify-on-shutdown/main.go
+// Look at the `ConfigureHost` too.
 //
 // See `Run` for more.
 func Server(srv *http.Server, hostConfigs ...host.Configurator) Runner {
@@ -448,6 +475,7 @@ func Server(srv *http.Server, hostConfigs ...host.Configurator) Runner {
 // i.e to add events for shutdown, serve or error.
 // An example of this use case can be found at:
 // https://github.com/kataras/iris/blob/master/_examples/http-listening/notify-on-shutdown/main.go
+// Look at the `ConfigureHost` too.
 //
 // See `Run` for more.
 func Addr(addr string, hostConfigs ...host.Configurator) Runner {
@@ -473,6 +501,7 @@ func Addr(addr string, hostConfigs ...host.Configurator) Runner {
 // i.e to add events for shutdown, serve or error.
 // An example of this use case can be found at:
 // https://github.com/kataras/iris/blob/master/_examples/http-listening/notify-on-shutdown/main.go
+// Look at the `ConfigureHost` too.
 //
 // See `Run` for more.
 func TLS(addr string, certFile, keyFile string, hostConfigs ...host.Configurator) Runner {
@@ -497,6 +526,7 @@ func TLS(addr string, certFile, keyFile string, hostConfigs ...host.Configurator
 // i.e to add events for shutdown, serve or error.
 // An example of this use case can be found at:
 // https://github.com/kataras/iris/blob/master/_examples/http-listening/notify-on-shutdown/main.go
+// Look at the `ConfigureHost` too.
 //
 // See `Run` for more.
 func AutoTLS(addr string, hostConfigs ...host.Configurator) Runner {