add some comments to iris.NewGuide and update httpexpect module

go.mod

@@ -18,7 +18,7 @@ require (
 	github.com/gomarkdown/markdown v0.0.0-20230716120725-531d2d74bc12
 	github.com/google/uuid v1.3.0
 	github.com/gorilla/securecookie v1.1.1
-	github.com/iris-contrib/httpexpect/v2 v2.12.1
+	github.com/iris-contrib/httpexpect/v2 v2.15.1
 	github.com/iris-contrib/schema v0.0.6
 	github.com/json-iterator/go v1.1.12
 	github.com/kataras/blocks v0.0.7
@@ -60,7 +60,9 @@ require (
 	github.com/dgryski/go-farm v0.0.0-20190423205320-6a90982ecee2 // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/fatih/color v1.15.0 // indirect
 	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/gobwas/httphead v0.1.0 // indirect
 	github.com/gobwas/pool v0.2.1 // indirect
 	github.com/gobwas/ws v1.3.0 // indirect
@@ -72,6 +74,7 @@ require (
 	github.com/iris-contrib/go.uuid v2.0.0+incompatible // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.19 // indirect
 	github.com/mediocregopher/radix/v3 v3.8.1 // indirect
 	github.com/minio/highwayhash v1.0.2 // indirect

go.sum

@@ -49,6 +49,8 @@ github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cu
 github.com/dustin/go-humanize v1.0.0/go.mod h1:HtrtbFcZ19U5GC7JDqmcUSB87Iq5E25KnS6fMYU6eOk=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/fatih/color v1.15.0 h1:kOqh6YHBtK8aywxGerMG2Eq3H6Qgoqeo13Bk2Mv/nBs=
+github.com/fatih/color v1.15.0/go.mod h1:0h5ZqXfHYED7Bhv2ZJamyIOUej9KtShiJESRwBDUSsw=
 github.com/fatih/structs v1.1.0 h1:Q7juDM0QtcnhCpeyLGQKyg4TOIghuNXrkL32pHAUMxo=
 github.com/fatih/structs v1.1.0/go.mod h1:9NiDSp5zOcgEDl+j00MP/WkGVPOlPRLejGD8Ga6PJ7M=
 github.com/flosch/pongo2/v4 v4.0.2 h1:gv+5Pe3vaSVmiJvh/BZa82b7/00YUGm0PIyVVLop0Hw=
@@ -59,6 +61,8 @@ github.com/fsnotify/fsnotify v1.6.0 h1:n+5WquG0fcWoWp6xPWfHdbskMCQaFnG6PfBrh1Ky4
 github.com/fsnotify/fsnotify v1.6.0/go.mod h1:sl3t1tCWJFWoRz9R8WJCbQihKKwmorjAbSClcnxKAGw=
 github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
 github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
+github.com/gobwas/glob v0.2.3 h1:A4xDbljILXROh+kObIiy5kIaPYD8e96x1tgBhUI5J+Y=
+github.com/gobwas/glob v0.2.3/go.mod h1:d3Ez4x06l9bZtSvzIay5+Yzi0fmZzPgnTbPcKjJAkT8=
 github.com/gobwas/httphead v0.1.0 h1:exrUm0f4YX0L7EBwZHuCF4GDp8aJfVeBrlLQrs6NqWU=
 github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM=
 github.com/gobwas/pool v0.2.1 h1:xfeeEhW7pwmX8nuLVlqbzVc7udMDrwetjEv+TZIz1og=
@@ -96,8 +100,8 @@ github.com/imkira/go-interpol v1.1.0/go.mod h1:z0h2/2T3XF8kyEPpRgJ3kmNv+C43p+I/C
 github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
 github.com/iris-contrib/go.uuid v2.0.0+incompatible h1:XZubAYg61/JwnJNbZilGjf3b3pB80+OQg2qf6c8BfWE=
 github.com/iris-contrib/go.uuid v2.0.0+incompatible/go.mod h1:iz2lgM/1UnEf1kP0L/+fafWORmlnuysV2EMP8MW+qe0=
-github.com/iris-contrib/httpexpect/v2 v2.12.1 h1:3cTZSyBBen/kfjCtgNFoUKi1u0FVXNaAjyRJOo6AVS4=
+github.com/iris-contrib/httpexpect/v2 v2.15.1 h1:G2/TW0EZ5UhNNdljNDBBQDfdfumLlV6ljRqdTk3cAmc=
-github.com/iris-contrib/httpexpect/v2 v2.12.1/go.mod h1:7+RB6W5oNClX7PTwJgJnsQP3ZuUUYB3u61KCqeSgZ88=
+github.com/iris-contrib/httpexpect/v2 v2.15.1/go.mod h1:cUwf1Mm5CWs5ahZNHtDq82WuGOitAWBg/eMGevX9ilg=
 github.com/iris-contrib/schema v0.0.6 h1:CPSBLyx2e91H2yJzPuhGuifVRnZBBJ3pCOMbOvPZaTw=
 github.com/iris-contrib/schema v0.0.6/go.mod h1:iYszG0IOsuIsfzjymw1kMzTL8YQcCWlm65f3wX8J5iA=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
@@ -135,6 +139,7 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
 github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
 github.com/mattn/go-isatty v0.0.19 h1:JITubQf0MOLdlGRuRq+jtsDlekdYPia9ZFsB8h/APPA=
 github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mediocregopher/radix/v3 v3.8.1 h1:rOkHflVuulFKlwsLY01/M2cM2tWCjDoETcMqKbAWu1M=
@@ -166,8 +171,8 @@ github.com/nxadm/tail v1.4.8 h1:nPr65rt6Y5JFSKQO7qToXr7pePgD6Gwiw05lkbyAQTE=
 github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU=
 github.com/onsi/ginkgo v1.16.5 h1:8xi0RTUf59SOSfEtZMvwTvXYMzG4gV23XVHOZiXNtnE=
 github.com/onsi/ginkgo v1.16.5/go.mod h1:+E8gABHa3K6zRBolWtd+ROzc/U5bkGt0FwiG042wbpU=
-github.com/onsi/gomega v1.27.1 h1:rfztXRbg6nv/5f+Raen9RcGoSecHIFgBBLQK3Wdj754=
+github.com/onsi/gomega v1.27.10 h1:naR28SdDFlqrG6kScpT8VWpu1xWY5nJRCF3XaYyBjhI=
-github.com/onsi/gomega v1.27.1/go.mod h1:aHX5xOykVYzWOV4WqQy0sy8BQptgukenXpCXfadcIAw=
+github.com/onsi/gomega v1.27.10/go.mod h1:RsS8tutOdbdgzbPtzzATp12yT7kM5I5aElG3evPbQ0M=
 github.com/pelletier/go-toml v1.2.0/go.mod h1:5z9KED0ma1S8pY6P1sdut58dfprrGBbd/94hg7ilaic=
 github.com/pkg/diff v0.0.0-20200914180035-5b29258ca4f7/go.mod h1:zO8QMzTeZd5cpnIkz/Gn6iK0jDfGicM1nynOkkPIl28=
 github.com/pkg/errors v0.8.1 h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=
@@ -293,6 +298,7 @@ golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20211019181941-9d821ace8654/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.2.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.10.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

iris_guide.go

@@ -216,65 +216,87 @@ import (
        return s.repos.Tests().ListTests(ctx)
    }
 */
-func NewGuide() Step1 {
+func NewGuide() Guide {
 	return &step1{}
 }
 
 type (
-	Step1 interface {
+	// Guide is the simplify API builder.
+	// It's a step-by-step builder which can be used to build an Iris Application
+	// with the most common features.
+	Guide interface {
 		// AllowOrigin defines the CORS allowed domains.
 		// Many can be splitted by comma.
 		// If "*" is provided then all origins are accepted (use it for public APIs).
-		AllowOrigin(originLine string) Step2
+		AllowOrigin(originLine string) CompressionGuide
 	}
 
-	Step2 interface {
+	// CompressionGuide is the 2nd step of the Guide.
+	// Compression (gzip or any other client requested) can be enabled or disabled.
+	CompressionGuide interface {
 		// Compression enables or disables the gzip (or any other client-preferred) compression algorithm
 		// for response writes.
-		Compression(b bool) Step3
+		Compression(b bool) HealthGuide
 	}
 
-	Step3 interface {
+	// HealthGuide is the 3rd step of the Guide.
+	// Health enables the /health route.
+	HealthGuide interface {
 		// Health enables the /health route.
 		// If "env" and "developer" are given, these fields will be populated to the client
 		// through headers and environment on health route.
-		Health(b bool, env, developer string) Step4
+		Health(b bool, env, developer string) TimeoutGuide
 	}
 
-	Step4 interface {
+	// TimeoutGuide is the 4th step of the Guide.
 	// Timeout defines the http timeout, server read & write timeouts.
-		Timeout(requestResponseLife, read time.Duration, write time.Duration) Step5
+	TimeoutGuide interface {
+		// Timeout defines the http timeout, server read & write timeouts.
+		Timeout(requestResponseLife, read time.Duration, write time.Duration) MiddlewareGuide
 	}
 
-	Step5 interface {
+	// MiddlewareGuide is the 5th step of the Guide.
+	// It registers one or more handlers to run before everything else (RouterMiddlewares) or
+	// before registered routes (Middlewares).
+	MiddlewareGuide interface {
 		// RouterMiddlewares registers one or more handlers to run before everything else.
-		RouterMiddlewares(handlers ...Handler) Step5
+		RouterMiddlewares(handlers ...Handler) MiddlewareGuide
 		// Middlewares registers one or more handlers to run before the requested route's handler.
-		Middlewares(handlers ...Handler) Step6
+		Middlewares(handlers ...Handler) ServiceGuide
 	}
 
-	Step6 interface {
+	// ServiceGuide is the 6th step of the Guide.
+	// It is used to register deferrable functions and, most importantly, dependencies that APIs can use.
+	ServiceGuide interface {
+		// Deferrables registers one or more functions to be ran when the server is terminated.
+		Deferrables(closers ...func()) ServiceGuide
 		// Services registers one or more dependencies that APIs can use.
-		Services(deps ...interface{}) Step7
+		Services(deps ...interface{}) ApplicationBuilder
 	}
 
-	Step7 interface {
+	// ApplicationBuilder is the final step of the Guide.
+	// It is used to register APIs controllers (PartyConfigurators) and
+	// its Build, Listen and Run methods configure and build the actual Iris application
+	// based on the previous steps.
+	ApplicationBuilder interface {
 		// Handle registers a simple route on specific method and (dynamic) path.
 		// It simply calls the Iris Application's Handle method.
 		// Use the "API" method instead to keep the app organized.
-		Handle(method, path string, handlers ...Handler) Step7
+		Handle(method, path string, handlers ...Handler) ApplicationBuilder
 		// API registers a router which is responsible to serve the /api group.
-		API(pathPrefix string, c ...router.PartyConfigurator) Step7
+		API(pathPrefix string, c ...router.PartyConfigurator) ApplicationBuilder
 		// Build builds the application with the prior configuration and returns the
 		// Iris Application instance for further customizations.
 		//
 		// Use "Build" before "Listen" or "Run" to apply further modifications
 		// to the framework before starting the server. Calling "Build" is optional.
 		Build() *Application // optional call.
-		// Listen calls the Application's Listen method.
+		// Listen calls the Application's Listen method which is a shortcut of Run(iris.Addr("hostPort")).
 		// Use "Run" instead if you need to customize the HTTP/2 server itself.
 		Listen(hostPort string, configurators ...Configurator) error // Listen OR Run.
 		// Run calls the Application's Run method.
+		// The 1st argument is a Runner (iris.Listener, iris.Server, iris.Addr, iris.TLS, iris.AutoTLS and iris.Raw).
+		// The 2nd argument can be used to add custom configuration right before the server is up and running.
 		Run(runner Runner, configurators ...Configurator) error
 	}
 )
@@ -283,7 +305,7 @@ type step1 struct {
 	originLine string
 }
 
-func (s *step1) AllowOrigin(originLine string) Step2 {
+func (s *step1) AllowOrigin(originLine string) CompressionGuide {
 	s.originLine = originLine
 	return &step2{
 		step1: s,
@@ -296,7 +318,7 @@ type step2 struct {
 	enableCompression bool
 }
 
-func (s *step2) Compression(b bool) Step3 {
+func (s *step2) Compression(b bool) HealthGuide {
 	s.enableCompression = b
 	return &step3{
 		step2: s,
@@ -310,7 +332,7 @@ type step3 struct {
 	env, developer string
 }
 
-func (s *step3) Health(b bool, env, developer string) Step4 {
+func (s *step3) Health(b bool, env, developer string) TimeoutGuide {
 	s.enableHealth = b
 	s.env, s.developer = env, developer
 	return &step4{
@@ -327,7 +349,7 @@ type step4 struct {
 	serverTimeoutWrite time.Duration
 }
 
-func (s *step4) Timeout(requestResponseLife, read, write time.Duration) Step5 {
+func (s *step4) Timeout(requestResponseLife, read, write time.Duration) MiddlewareGuide {
 	s.handlerTimeout = requestResponseLife
 
 	s.serverTimeoutRead = read
@@ -344,12 +366,12 @@ type step5 struct {
 	middlewares       []Handler
 }
 
-func (s *step5) RouterMiddlewares(handlers ...Handler) Step5 {
+func (s *step5) RouterMiddlewares(handlers ...Handler) MiddlewareGuide {
 	s.routerMiddlewares = append(s.routerMiddlewares, handlers...)
 	return s
 }
 
-func (s *step5) Middlewares(handlers ...Handler) Step6 {
+func (s *step5) Middlewares(handlers ...Handler) ServiceGuide {
 	s.middlewares = handlers
 
 	return &step6{
@@ -367,7 +389,12 @@ type step6 struct {
 	configuratorsAsDeps []Configurator
 }
 
-func (s *step6) Services(deps ...interface{}) Step7 {
+func (s *step6) Deferrables(closers ...func()) ServiceGuide {
+	s.closers = append(s.closers, closers...)
+	return s
+}
+
+func (s *step6) Services(deps ...interface{}) ApplicationBuilder {
 	s.deps = deps
 	for _, d := range deps {
 		if d == nil {
@@ -409,12 +436,12 @@ type step7SimpleRoute struct {
 	handlers     []Handler
 }
 
-func (s *step7) Handle(method, path string, handlers ...Handler) Step7 {
+func (s *step7) Handle(method, path string, handlers ...Handler) ApplicationBuilder {
 	s.handlers = append(s.handlers, step7SimpleRoute{method: method, path: path, handlers: handlers})
 	return s
 }
 
-func (s *step7) API(prefix string, c ...router.PartyConfigurator) Step7 {
+func (s *step7) API(prefix string, c ...router.PartyConfigurator) ApplicationBuilder {
 	if s.m == nil {
 		s.m = make(map[string][]router.PartyConfigurator)
 	}