add a way to customize the handler names (recommended: before server execution) so route logging can be more human-friendly on handlers like standard iris middlewares, e.g. request logger

Former-commit-id: 039c233f2d4da0d52b1d6fc86b6d73be14b15608

core/router/api_builder.go

@@ -452,10 +452,13 @@ func (api *APIBuilder) CreateRoutes(methods []string, relativePath string, handl
 	mainHandlers := context.Handlers(handlers)
 	// before join the middleware + handlers + done handlers and apply the execution rules.
 
-	possibleMainHandlerName, mainHandlerIndex := context.MainHandlerName(mainHandlers)
+	mainHandlerName, mainHandlerIndex := context.MainHandlerName(mainHandlers)
 	wd, _ := os.Getwd()
 	mainHandlerFileName, mainHandlerFileNumber := context.HandlerFileLineRel(handlers[mainHandlerIndex], wd)
 
+	// re-calculate mainHandlerIndex in favor of the middlewares.
+	mainHandlerIndex = len(api.middleware) + len(api.beginGlobalHandlers) + mainHandlerIndex
+
 	// TODO: for UseGlobal/DoneGlobal that doesn't work.
 	applyExecutionRules(api.handlerExecutionRules, &beginHandlers, &doneHandlers, &mainHandlers)
 
@@ -474,18 +477,23 @@ func (api *APIBuilder) CreateRoutes(methods []string, relativePath string, handl
 	routes := make([]*Route, len(methods))
 
 	for i, m := range methods {
-		route, err := NewRoute(m, subdomain, path, possibleMainHandlerName, routeHandlers, *api.macros)
+		route, err := NewRoute(m, subdomain, path, routeHandlers, *api.macros)
 		if err != nil { // template path parser errors:
 			api.errors.Addf("[%s:%d] %v -> %s:%s:%s", filename, line, err, m, subdomain, path)
 			continue
 		}
 
-		route.SourceFileName = mainHandlerFileName
-		route.SourceLineNumber = mainHandlerFileNumber
-
+		// The caller tiself, if anonymous, it's the first line of `app.X("/path", here)`
 		route.RegisterFileName = filename
 		route.RegisterLineNumber = line
 
+		route.MainHandlerName = mainHandlerName
+		route.MainHandlerIndex = mainHandlerIndex
+
+		// The main handler source, could be the same as the register's if anonymous.
+		route.SourceFileName = mainHandlerFileName
+		route.SourceLineNumber = mainHandlerFileNumber
+
 		// Add UseGlobal & DoneGlobal Handlers
 		route.Use(api.beginGlobalHandlers...)
 		route.Done(api.doneGlobalHandlers...)

core/router/handler.go

@@ -174,7 +174,7 @@ func (h *routerHandler) Build(provider RoutesProvider) error {
 		defer golog.SetTimeFormat(bckpTimeFormat)
 		golog.SetTimeFormat("")
 
-		for _, method := range AllMethods { // TODO: MethodNone "NONE" with an (offline) status on r.Trace.
+		for _, method := range append(AllMethods, MethodNone) {
 			methodRoutes := collect(method)
 			for _, r := range methodRoutes {
 				golog.Println(r.Trace())

core/router/route.go

@@ -29,8 +29,9 @@ type Route struct {
 	beginHandlers context.Handlers
 	// Handlers are the main route's handlers, executed by order.
 	// Cannot be empty.
-	Handlers        context.Handlers `json:"-"`
-	MainHandlerName string           `json:"mainHandlerName"`
+	Handlers         context.Handlers `json:"-"`
+	MainHandlerName  string           `json:"mainHandlerName"`
+	MainHandlerIndex int              `json:"mainHandlerIndex"`
 	// temp storage, they're appended to the Handlers on build.
 	// Execution happens after Begin and main Handler(s), can be empty.
 	doneHandlers context.Handlers
@@ -67,7 +68,7 @@ type Route struct {
 // handlers and the macro container which all routes should share.
 // It parses the path based on the "macros",
 // handlers are being changed to validate the macros at serve time, if needed.
-func NewRoute(method, subdomain, unparsedPath, mainHandlerName string,
+func NewRoute(method, subdomain, unparsedPath string,
 	handlers context.Handlers, macros macro.Macros) (*Route, error) {
 	tmpl, err := macro.Parse(unparsedPath, macros)
 	if err != nil {
@@ -87,15 +88,14 @@ func NewRoute(method, subdomain, unparsedPath, mainHandlerName string,
 	formattedPath := formatPath(path)
 
 	route := &Route{
-		Name:            defaultName,
-		Method:          method,
-		methodBckp:      method,
-		Subdomain:       subdomain,
-		tmpl:            tmpl,
-		Path:            path,
-		Handlers:        handlers,
-		MainHandlerName: mainHandlerName,
-		FormattedPath:   formattedPath,
+		Name:          defaultName,
+		Method:        method,
+		methodBckp:    method,
+		Subdomain:     subdomain,
+		tmpl:          tmpl,
+		Path:          path,
+		Handlers:      handlers,
+		FormattedPath: formattedPath,
 	}
 
 	return route, nil
@@ -357,20 +357,17 @@ func ignoreHandlerTrace(name string) bool {
 	return false
 }
 
-func traceHandlerFile(name, line string, number int, seen map[string]struct{}) string {
+func traceHandlerFile(name, line string, number int) string {
 	file := fmt.Sprintf("(%s:%d)", line, number)
 
-	if _, printed := seen[file]; printed {
-		return ""
-	}
-
-	seen[file] = struct{}{}
-
 	// trim the path for Iris' internal middlewares, e.g.
 	// irs/mvc.GRPC.Apply.func1
-	if internalName := "github.com/kataras/iris/v12"; strings.HasPrefix(name, internalName) {
+	if internalName := context.PackageName; strings.HasPrefix(name, internalName) {
 		name = strings.Replace(name, internalName, "iris", 1)
 	}
+	if internalName := "github.com/iris-contrib/middleware"; strings.HasPrefix(name, internalName) {
+		name = strings.Replace(name, internalName, "iris-contrib", 1)
+	}
 
 	if ignoreHandlerTrace(name) {
 		return ""
@@ -408,6 +405,8 @@ func (r *Route) Trace() string {
 		color = pio.Gray
 	case http.MethodTrace:
 		color = pio.Yellow
+	case MethodNone:
+		color = 196 // full red.
 	}
 
 	path := r.Tmpl().Src
@@ -419,36 +418,60 @@ func (r *Route) Trace() string {
 	s := fmt.Sprintf("%s: %s", pio.Rich(r.Method, color), path)
 
 	// (@description)
-	if r.Description != "" {
-		s += fmt.Sprintf(" %s", pio.Rich(r.Description, pio.Cyan, pio.Underline))
+	description := r.Description
+	if description == "" && r.Method == MethodNone {
+		description = "offline"
+	}
+
+	if description != "" {
+		s += fmt.Sprintf(" %s", pio.Rich(description, pio.Cyan, pio.Underline))
 	}
 
 	// (@route_rel_location)
 	s += fmt.Sprintf(" (%s:%d)", r.RegisterFileName, r.RegisterLineNumber)
 
-	seen := make(map[string]struct{})
-
-	// if the main handler is not an anonymous function (so, differs from @route_rel_location)
-	// then * @handler_name (@handler_rel_location)
-	if r.SourceFileName != r.RegisterFileName || r.SourceLineNumber != r.RegisterLineNumber {
-		s += traceHandlerFile(r.MainHandlerName, r.SourceFileName, r.SourceLineNumber, seen)
-	}
-
 	wd, _ := os.Getwd()
 
-	for _, h := range r.Handlers {
-		name := context.HandlerName(h)
-		if name == r.MainHandlerName {
-			continue
+	for i, h := range r.Handlers {
+		// main handler info can be programmatically
+		// changed to be more specific, respect those options.
+		var (
+			name string
+			file string
+			line int
+		)
+
+		// name = context.HandlerName(h)
+		// file, line = context.HandlerFileLineRel(h, wd)
+		// fmt.Printf("---handler index: %d, name: %s, line: %s:%d\n", i, name, file, line)
+
+		if i == r.MainHandlerIndex {
+			name = r.MainHandlerName
+			file = r.SourceFileName
+			line = r.SourceLineNumber
+			// fmt.Printf("main handler index: %d, name: %s, line: %d\n", i, name, line)
+		} else {
+			name = context.HandlerName(h)
+			file, line = context.HandlerFileLineRel(h, wd)
+
+			// If a middleware, e.g (macro) which changes the main handler index,
+			// skip it.
+			if file == r.SourceFileName && line == r.SourceLineNumber {
+				// fmt.Printf("[0] SKIP: handler index: %d, name: %s, line: %s:%d\n", i, name, file, line)
+				continue
+			}
+			// fmt.Printf("handler index: %d, name: %s, line: %d\n", i, name, line)
 		}
 
-		file, line := context.HandlerFileLineRel(h, wd)
+		// If a handler is an anonymous function then it was already
+		// printed in the first line, skip it.
 		if file == r.RegisterFileName && line == r.RegisterLineNumber {
+			// fmt.Printf("[1] SKIP: handler index: %d, name: %s, line: %s:%d\n", i, name, file, line)
 			continue
 		}
 
 		// * @handler_name (@handler_rel_location)
-		s += traceHandlerFile(name, file, line, seen)
+		s += traceHandlerFile(name, file, line)
 	}
 
 	return s
@@ -486,6 +509,10 @@ func (rd routeReadOnlyWrapper) MainHandlerName() string {
 	return rd.Route.MainHandlerName
 }
 
+func (rd routeReadOnlyWrapper) MainHandlerIndex() int {
+	return rd.Route.MainHandlerIndex
+}
+
 func (rd routeReadOnlyWrapper) StaticSites() []context.StaticSite {
 	return rd.Route.StaticSites
 }