reorganization of _examples and add some new examples such as iris+groupcache+mysql+docker

Former-commit-id: ed635ee95de7160cde11eaabc0c1dcb0e460a620

_examples/routing/subdomains/multi/hosts

@@ -0,0 +1,28 @@
+# Copyright (c) 1993-2009 Microsoft Corp.
+#
+# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
+#
+# This file contains the mappings of IP addresses to host names. Each
+# entry should be kept on an individual line. The IP address should
+# be placed in the first column followed by the corresponding host name.
+# The IP address and the host name should be separated by at least one
+# space.
+#
+# Additionally, comments (such as these) may be inserted on individual
+# lines or following the machine name denoted by a '#' symbol.
+#
+# For example:
+#
+#      102.54.94.97     rhino.acme.com          # source server
+#       38.25.63.10     x.acme.com              # x client host
+
+# localhost name resolution is handled within DNS itself.
+127.0.0.1       localhost
+::1             localhost
+#-iris-For development machine, you have to configure your dns also for online, search google how to do it if you don't know
+
+127.0.0.1 domain.local
+127.0.0.1 system.domain.local
+127.0.0.1 dashboard.domain.local
+
+#-END iris-

_examples/routing/subdomains/multi/main.go

@@ -0,0 +1,40 @@
+package main
+
+import (
+	"github.com/kataras/iris/v12"
+)
+
+func main() {
+	app := iris.New()
+
+	/*
+	 * Setup static files
+	 */
+
+	app.HandleDir("/assets", "./public/assets")
+	app.HandleDir("/upload_resources", "./public/upload_resources")
+
+	dashboard := app.Party("dashboard.")
+	{
+		dashboard.Get("/", func(ctx iris.Context) {
+			ctx.Writef("HEY FROM dashboard")
+		})
+	}
+	system := app.Party("system.")
+	{
+		system.Get("/", func(ctx iris.Context) {
+			ctx.Writef("HEY FROM system")
+		})
+	}
+
+	app.Get("/", func(ctx iris.Context) {
+		ctx.Writef("HEY FROM frontend /")
+	})
+	// http://domain.local:80
+	// http://dashboard.local
+	// http://system.local
+	// Make sure you prepend the "http" in your browser
+	// because .local is a virtual domain we think to show case you
+	// that you can declare any syntactical correct name as a subdomain in iris.
+	app.Listen("domain.local:80") // for beginners: look ../hosts file
+}

_examples/routing/subdomains/redirect/hosts

@@ -0,0 +1,4 @@
+127.0.0.1	mydomain.com
+127.0.0.1	www.mydomain.com
+
+# Windows: Drive:/Windows/system32/drivers/etc/hosts, on Linux: /etc/hosts

_examples/routing/subdomains/redirect/main.go

@@ -0,0 +1,73 @@
+// Package main shows how to register a simple 'www' subdomain,
+// using the `app.WWW` method, which will register a router wrapper which will
+// redirect all 'mydomain.com' requests to 'www.mydomain.com'.
+// Check the 'hosts' file to see how to test the 'mydomain.com' on your local machine.
+package main
+
+import "github.com/kataras/iris/v12"
+
+const addr = "mydomain.com:80"
+
+func main() {
+	app := newApp()
+
+	// http(s)://mydomain.com, will be redirect to http(s)://www.mydomain.com.
+	// The `www` variable is the `app.Subdomain("www")`.
+	//
+	// app.WWW() wraps the router so it can redirect all incoming requests
+	// that comes from 'http(s)://mydomain.com/%path%' (www is missing)
+	// to `http(s)://www.mydomain.com/%path%`.
+	//
+	// Try:
+	// http://mydomain.com             -> http://www.mydomain.com
+	// http://mydomain.com/users       -> http://www.mydomain.com/users
+	// http://mydomain.com/users/login -> http://www.mydomain.com/users/login
+	app.Listen(addr)
+}
+
+func newApp() *iris.Application {
+	app := iris.New()
+	app.Get("/", func(ctx iris.Context) {
+		ctx.Writef("This will never be executed.")
+	})
+
+	www := app.Subdomain("www") // <- same as app.Party("www.")
+	www.Get("/", index)
+
+	// www is an `iris.Party`, use it like you already know, like grouping routes.
+	www.PartyFunc("/users", func(p iris.Party) { // <- same as www.Party("/users").Get(...)
+		p.Get("/", usersIndex)
+		p.Get("/login", getLogin)
+	})
+
+	// redirects mydomain.com/%anypath% to www.mydomain.com/%anypath%.
+	// First argument is the 'from' and second is the 'to/target'.
+	app.SubdomainRedirect(app, www)
+
+	// SubdomainRedirect works for multi-level subdomains as well:
+	// subsub := www.Subdomain("subsub") // subsub.www.mydomain.com
+	// subsub.Get("/", func(ctx iris.Context) { ctx.Writef("subdomain is: " + ctx.Subdomain()) })
+	// app.SubdomainRedirect(subsub, www)
+	//
+	// If you need to redirect any subdomain to 'www' then:
+	// app.SubdomainRedirect(app.WildcardSubdomain(), www)
+	// If you need to redirect from a subdomain to the root domain then:
+	// app.SubdomainRedirect(app.Subdomain("mysubdomain"), app)
+	//
+	// Note that app.Party("mysubdomain.") and app.Subdomain("mysubdomain")
+	// is the same exactly thing, the difference is that the second can omit the last dot('.').
+
+	return app
+}
+
+func index(ctx iris.Context) {
+	ctx.Writef("This is the www.mydomain.com endpoint.")
+}
+
+func usersIndex(ctx iris.Context) {
+	ctx.Writef("This is the www.mydomain.com/users endpoint.")
+}
+
+func getLogin(ctx iris.Context) {
+	ctx.Writef("This is the www.mydomain.com/users/login endpoint.")
+}

_examples/routing/subdomains/redirect/main_test.go

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/kataras/iris/v12/httptest"
+)
+
+func TestSubdomainRedirectWWW(t *testing.T) {
+	app := newApp()
+	root := strings.TrimSuffix(addr, ":80")
+
+	e := httptest.New(t, app)
+
+	tests := []struct {
+		path     string
+		response string
+	}{
+		{"/", fmt.Sprintf("This is the www.%s endpoint.", root)},
+		{"/users", fmt.Sprintf("This is the www.%s/users endpoint.", root)},
+		{"/users/login", fmt.Sprintf("This is the www.%s/users/login endpoint.", root)},
+	}
+
+	for _, test := range tests {
+		e.GET(test.path).Expect().Status(httptest.StatusOK).Body().Equal(test.response)
+	}
+}

_examples/routing/subdomains/single/hosts

@@ -0,0 +1,27 @@
+# Copyright (c) 1993-2009 Microsoft Corp.
+#
+# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
+#
+# This file contains the mappings of IP addresses to host names. Each
+# entry should be kept on an individual line. The IP address should
+# be placed in the first column followed by the corresponding host name.
+# The IP address and the host name should be separated by at least one
+# space.
+#
+# Additionally, comments (such as these) may be inserted on individual
+# lines or following the machine name denoted by a '#' symbol.
+#
+# For example:
+#
+#      102.54.94.97     rhino.acme.com          # source server
+#       38.25.63.10     x.acme.com              # x client host
+
+# localhost name resolution is handled within DNS itself.
+127.0.0.1       localhost
+::1             localhost
+#-iris-For development machine, you have to configure your dns also for online, search google how to do it if you don't know
+
+127.0.0.1		mydomain.com
+127.0.0.1		admin.mydomain.com
+
+#-END iris-

_examples/routing/subdomains/single/main.go

@@ -0,0 +1,44 @@
+// Package main register static subdomains, simple as parties, check ./hosts if you use windows
+package main
+
+import (
+	"github.com/kataras/iris/v12"
+)
+
+func main() {
+	app := iris.New()
+
+	// Subdomain method is just another Party.
+	admin := app.Subdomain("admin")
+	{
+		// admin.mydomain.com
+		admin.Get("/", func(c iris.Context) {
+			c.Writef("INDEX FROM admin.mydomain.com")
+		})
+		// admin.mydomain.com/hey
+		admin.Get("/hey", func(c iris.Context) {
+			c.Writef("HEY FROM admin.mydomain.com/hey")
+		})
+		// admin.mydomain.com/hey2
+		admin.Get("/hey2", func(c iris.Context) {
+			c.Writef("HEY SECOND FROM admin.mydomain.com/hey")
+		})
+	}
+
+	// mydomain.com
+	app.Get("/", func(c iris.Context) {
+		c.Writef("INDEX FROM no-subdomain hey")
+	})
+
+	// mydomain.com/hey
+	app.Get("/hey", func(c iris.Context) {
+		c.Writef("HEY FROM no-subdomain hey")
+	})
+
+	// http://admin.mydomain.com
+	// http://admin.mydomain.com/hey
+	// http://admin.mydomain.com/hey2
+	// http://mydomain.com
+	// http://mydomain.com/hey
+	app.Listen("mydomain.com:80") // for beginners: look ../hosts file
+}

_examples/routing/subdomains/wildcard/hosts

@@ -0,0 +1,30 @@
+# Copyright (c) 1993-2009 Microsoft Corp.
+#
+# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
+#
+# This file contains the mappings of IP addresses to host names. Each
+# entry should be kept on an individual line. The IP address should
+# be placed in the first column followed by the corresponding host name.
+# The IP address and the host name should be separated by at least one
+# space.
+#
+# Additionally, comments (such as these) may be inserted on individual
+# lines or following the machine name denoted by a '#' symbol.
+#
+# For example:
+#
+#      102.54.94.97     rhino.acme.com          # source server
+#       38.25.63.10     x.acme.com              # x client host
+
+# localhost name resolution is handled within DNS itself.
+127.0.0.1       localhost
+::1             localhost
+#-iris-For development machine, you have to configure your dns also for online, search google how to do it if you don't know
+127.0.0.1		mydomain.com
+127.0.0.1		username1.mydomain.com
+127.0.0.1		username2.mydomain.com
+127.0.0.1		username3.mydomain.com
+127.0.0.1		username4.mydomain.com
+127.0.0.1		username5.mydomain.com
+
+#-END iris-

_examples/routing/subdomains/wildcard/main.go

@@ -0,0 +1,71 @@
+// Package main an example on how to catch dynamic subdomains - wildcard.
+// On the first example we learnt how to create routes for static subdomains, subdomains you know that you will have.
+// Here we will see an example how to catch unknown subdomains, dynamic subdomains, like username.mydomain.com:8080.
+package main
+
+import (
+	"github.com/kataras/iris/v12"
+)
+
+// register a dynamic-wildcard subdomain to your server machine(dns/...) first, check ./hosts if you use windows.
+// run this file and try to redirect: http://username1.mydomain.com:8080/ , http://username2.mydomain.com:8080/ , http://username1.mydomain.com/something, http://username1.mydomain.com/something/sadsadsa
+
+func main() {
+	app := iris.New()
+
+	/* Keep note that you can use both type of subdomains (named and wildcard(*.) )
+	   admin.mydomain.com,  and for other the Party(*.) but this is not this example's purpose
+
+	admin := app.Party("admin.")
+	{
+		// admin.mydomain.com
+		admin.Get("/", func(ctx iris.Context) {
+			ctx.Writef("INDEX FROM admin.mydomain.com")
+		})
+		// admin.mydomain.com/hey
+		admin.Get("/hey", func(ctx iris.Context) {
+			ctx.Writef("HEY FROM admin.mydomain.com/hey")
+		})
+		// admin.mydomain.com/hey2
+		admin.Get("/hey2", func(ctx iris.Context) {
+			ctx.Writef("HEY SECOND FROM admin.mydomain.com/hey")
+		})
+	}*/
+
+	// no order, you can register subdomains at the end also.
+	dynamicSubdomains := app.Party("*.")
+	{
+		dynamicSubdomains.Get("/", dynamicSubdomainHandler)
+
+		dynamicSubdomains.Get("/something", dynamicSubdomainHandler)
+
+		dynamicSubdomains.Get("/something/{paramfirst}", dynamicSubdomainHandlerWithParam)
+	}
+
+	app.Get("/", func(ctx iris.Context) {
+		ctx.Writef("Hello from mydomain.com path: %s", ctx.Path())
+	})
+
+	app.Get("/hello", func(ctx iris.Context) {
+		ctx.Writef("Hello from mydomain.com path: %s", ctx.Path())
+	})
+
+	// http://mydomain.com:8080
+	// http://username1.mydomain.com:8080
+	// http://username2.mydomain.com:8080/something
+	// http://username3.mydomain.com:8080/something/yourname
+	app.Listen("mydomain.com:8080") // for beginners: look ../hosts file
+}
+
+func dynamicSubdomainHandler(ctx iris.Context) {
+	username := ctx.Subdomain()
+	ctx.Writef("Hello from dynamic subdomain path: %s, here you can handle the route for dynamic subdomains, handle the user: %s", ctx.Path(), username)
+	// if  http://username4.mydomain.com:8080/ prints:
+	// Hello from dynamic subdomain path: /, here you can handle the route for dynamic subdomains, handle the user: username4
+}
+
+func dynamicSubdomainHandlerWithParam(ctx iris.Context) {
+	username := ctx.Subdomain()
+	ctx.Writef("Hello from dynamic subdomain path: %s, here you can handle the route for dynamic subdomains, handle the user: %s", ctx.Path(), username)
+	ctx.Writef("The paramfirst is: %s", ctx.Params().Get("paramfirst"))
+}

_examples/routing/subdomains/www/hosts

@@ -0,0 +1,25 @@
+# Copyright (c) 1993-2009 Microsoft Corp.
+#
+# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
+#
+# This file contains the mappings of IP addresses to host names. Each
+# entry should be kept on an individual line. The IP address should
+# be placed in the first column followed by the corresponding host name.
+# The IP address and the host name should be separated by at least one
+# space.
+#
+# Additionally, comments (such as these) may be inserted on individual
+# lines or following the machine name denoted by a '#' symbol.
+#
+# For example:
+#
+#      102.54.94.97     rhino.acme.com          # source server
+#       38.25.63.10     x.acme.com              # x client host
+
+# localhost name resolution is handled within DNS itself.
+127.0.0.1       localhost
+::1             localhost
+#-iris-For development machine, you have to configure your dns also for online, search google how to do it if you don't know
+127.0.0.1		mydomain.com
+127.0.0.1		www.mydomain.com
+#-END iris-

_examples/routing/subdomains/www/main.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"github.com/kataras/iris/v12"
+)
+
+func newApp() *iris.Application {
+	app := iris.New()
+
+	app.Get("/", info)
+	app.Get("/about", info)
+	app.Get("/contact", info)
+
+	app.PartyFunc("/api/users", func(r iris.Party) {
+		r.Get("/", info)
+		r.Get("/{id:uint64}", info)
+
+		r.Post("/", info)
+
+		r.Put("/{id:uint64}", info)
+	}) /* <- same as:
+	 usersAPI := app.Party("/api/users")
+	 {  // those brackets are just syntactic-sugar things.
+		// This method is rarely used but you can make use of it when you want
+	    // scoped variables to that code block only.
+		usersAPI.Get/Post...
+	 }
+	 usersAPI.Get/Post...
+	*/
+
+	www := app.Party("www.")
+	{
+		// Just to show how you can get all routes and copy them to another
+		// party or subdomain:
+		// Get all routes that are registered so far, including all "Parties" and subdomains:
+		currentRoutes := app.GetRoutes()
+		// Register them to the www subdomain/vhost as well:
+		for _, r := range currentRoutes {
+			www.Handle(r.Method, r.Tmpl().Src, r.Handlers...)
+		}
+
+		// http://www.mydomain.com/hi
+		www.Get("/hi", func(ctx iris.Context) {
+			ctx.Writef("hi from www.mydomain.com")
+		})
+	}
+	// See also the "subdomains/redirect" to register redirect router wrappers between subdomains,
+	// i.e mydomain.com to www.mydomain.com (like facebook does for SEO reasons(;)).
+
+	return app
+}
+
+func main() {
+	app := newApp()
+	// http://mydomain.com
+	// http://mydomain.com/about
+	// http://imydomain.com/contact
+	// http://mydomain.com/api/users
+	// http://mydomain.com/api/users/42
+
+	// http://www.mydomain.com
+	// http://www.mydomain.com/hi
+	// http://www.mydomain.com/about
+	// http://www.mydomain.com/contact
+	// http://www.mydomain.com/api/users
+	// http://www.mydomain.com/api/users/42
+	if err := app.Listen("mydomain.com:80"); err != nil {
+		panic(err)
+	}
+}
+
+func info(ctx iris.Context) {
+	method := ctx.Method()
+	subdomain := ctx.Subdomain()
+	path := ctx.Path()
+
+	ctx.Writef("\nInfo\n\n")
+	ctx.Writef("Method: %s\nSubdomain: %s\nPath: %s", method, subdomain, path)
+}

_examples/routing/subdomains/www/main_test.go

@@ -0,0 +1,57 @@
+package main
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/kataras/iris/v12/httptest"
+)
+
+type testRoute struct {
+	path      string
+	method    string
+	subdomain string
+}
+
+func (r testRoute) response() string {
+	msg := fmt.Sprintf("\nInfo\n\nMethod: %s\nSubdomain: %s\nPath: %s", r.method, r.subdomain, r.path)
+	return msg
+}
+
+func TestSubdomainWWW(t *testing.T) {
+	app := newApp()
+
+	tests := []testRoute{
+		// host
+		{"/", "GET", ""},
+		{"/about", "GET", ""},
+		{"/contact", "GET", ""},
+		{"/api/users", "GET", ""},
+		{"/api/users/42", "GET", ""},
+		{"/api/users", "POST", ""},
+		{"/api/users/42", "PUT", ""},
+		// www sub domain
+		{"/", "GET", "www"},
+		{"/about", "GET", "www"},
+		{"/contact", "GET", "www"},
+		{"/api/users", "GET", "www"},
+		{"/api/users/42", "GET", "www"},
+		{"/api/users", "POST", "www"},
+		{"/api/users/42", "PUT", "www"},
+	}
+
+	host := "localhost:1111"
+	e := httptest.New(t, app, httptest.Debug(false))
+
+	for _, test := range tests {
+
+		req := e.Request(test.method, test.path)
+		if subdomain := test.subdomain; subdomain != "" {
+			req.WithURL("http://" + subdomain + "." + host)
+		}
+
+		req.Expect().
+			Status(httptest.StatusOK).
+			Body().Equal(test.response())
+	}
+}