Finalize initial interceptor implementation

Author: raphael

codegen/cli/cli.go

@@ -702,7 +702,8 @@ const parseFlagsT = `var (
 `
 
 // input: commandData
-const commandUsageT = `{{ printf "%sUsage displays the usage of the %s command and its subcommands." .Name .Name | comment }}
+const commandUsageT = `
+{{ printf "%sUsage displays the usage of the %s command and its subcommands." .VarName .Name | comment }}
 func {{ .VarName }}Usage() {
 	fmt.Fprintf(os.Stderr, ` + "`" + `{{ printDescription .Description }}
 Usage:

codegen/example/templates/server_interceptors.go.tpl

@@ -8,16 +8,12 @@
 			{{- end }}
 		{{- end }}
 	)
-	{{- end }}
-	{{- if .HasInterceptors }}
 	{
-	{{- end }}
 	{{- range .Services }}
 		{{- if and .Methods .ServerInterceptors }}
 		{{ .VarName }}Interceptors = {{ $.InterPkg }}.New{{ .StructName }}ServerInterceptors()
 		{{- end }}
 	{{- end }}
-	{{- if .HasInterceptors }}
 	}
 	{{- end }}
 {{- end }}

codegen/service/client.go

@@ -15,7 +15,7 @@ const (
 // ClientFile returns the client file for the given service.
 func ClientFile(_ string, service *expr.ServiceExpr) *codegen.File {
 	svc := Services.Get(service.Name)
-	data := endpointData(service)
+	data := endpointData(svc)
 	path := filepath.Join(codegen.Gendir, svc.PathName, "client.go")
 	var (
 		sections []*codegen.SectionTemplate

codegen/service/endpoint.go

@@ -50,10 +50,6 @@ type (
 		ServiceName string
 		// ServiceVarName is the name of the owner service Go interface.
 		ServiceVarName string
-		// ServerInterceptors contains the server-side interceptors for this method
-		ServerInterceptors []*InterceptorData
-		// ClientInterceptors contains the client-side interceptors for this method
-		ClientInterceptors []*InterceptorData
 	}
 )
 
@@ -71,7 +67,7 @@ func EndpointFile(genpkg string, service *expr.ServiceExpr) *codegen.File {
 	svc := Services.Get(service.Name)
 	svcName := svc.PathName
 	path := filepath.Join(codegen.Gendir, svcName, "endpoints.go")
-	data := endpointData(service)
+	data := endpointData(svc)
 	var (
 		sections []*codegen.SectionTemplate
 	)
@@ -138,25 +134,22 @@ func EndpointFile(genpkg string, service *expr.ServiceExpr) *codegen.File {
 	return &codegen.File{Path: path, SectionTemplates: sections}
 }
 
-func endpointData(service *expr.ServiceExpr) *EndpointsData {
-	svc := Services.Get(service.Name)
+func endpointData(svc *Data) *EndpointsData {
 	methods := make([]*EndpointMethodData, len(svc.Methods))
 	names := make([]string, len(svc.Methods))
 	for i, m := range svc.Methods {
 		methods[i] = &EndpointMethodData{
-			MethodData:         m,
-			ArgName:            codegen.Goify(m.VarName, false),
-			ServiceName:        svc.Name,
-			ServiceVarName:     serviceInterfaceName,
-			ClientVarName:      clientStructName,
-			ServerInterceptors: m.ServerInterceptors,
-			ClientInterceptors: m.ClientInterceptors,
+			MethodData:     m,
+			ArgName:        codegen.Goify(m.VarName, false),
+			ServiceName:    svc.Name,
+			ServiceVarName: serviceInterfaceName,
+			ClientVarName:  clientStructName,
 		}
 		names[i] = codegen.Goify(m.VarName, false)
 	}
-	desc := fmt.Sprintf("%s wraps the %q service endpoints.", endpointsStructName, service.Name)
+	desc := fmt.Sprintf("%s wraps the %q service endpoints.", endpointsStructName, svc.Name)
 	return &EndpointsData{
-		Name:                  service.Name,
+		Name:                  svc.Name,
 		Description:           desc,
 		VarName:               endpointsStructName,
 		ClientVarName:         clientStructName,

codegen/service/example_interceptors.go

@@ -49,7 +49,7 @@ func exampleInterceptorsFile(genpkg string, svc *expr.ServiceExpr) []*codegen.Fi
 						{Path: path.Join(genpkg, sdata.PathName), Name: sdata.PkgName},
 					}),
 					{
-						Name:   "server-interceptor",
+						Name:   "exmaple-server-interceptor",
 						Source: readTemplate("example_server_interceptor"),
 						Data:   data,
 					},
@@ -73,7 +73,7 @@ func exampleInterceptorsFile(genpkg string, svc *expr.ServiceExpr) []*codegen.Fi
 						{Path: path.Join(genpkg, sdata.PathName), Name: sdata.PkgName},
 					}),
 					{
-						Name:   "client-interceptor",
+						Name:   "example-client-interceptor",
 						Source: readTemplate("example_client_interceptor"),
 						Data:   data,
 					},

codegen/service/interceptors.go

@@ -29,35 +29,41 @@ func InterceptorsFiles(genpkg string, service *expr.ServiceExpr) []*codegen.File
 }
 
 // interceptorFile returns the file defining the interceptors.
+// This method is called twice, once for the server and once for the client.
 func interceptorFile(svc *Data, server bool) *codegen.File {
 	filename := "client_interceptors.go"
 	template := "client_interceptors"
-	section := "client-interceptors"
+	section := "client-interceptors-type"
 	desc := "Client Interceptors"
-	var data []*InterceptorData
 	if server {
 		filename = "service_interceptors.go"
 		template = "server_interceptors"
-		section = "server-interceptors"
+		section = "server-interceptors-type"
 		desc = "Server Interceptors"
-		data = svc.ServerInterceptors
 	}
 	desc = svc.Name + desc
 	path := filepath.Join(codegen.Gendir, svc.PathName, filename)
 
+	interceptors := svc.ServerInterceptors
 	if !server {
-		// We don't want to generate duplicate interceptor info data structures for
-		// interceptors that are both server and client side.
-		serverInterceptors := make(map[string]struct{}, len(svc.ServerInterceptors))
-		for _, intr := range svc.ServerInterceptors {
-			serverInterceptors[intr.Name] = struct{}{}
+		interceptors = svc.ClientInterceptors
+	}
+
+	// We don't want to generate duplicate interceptor info data structures for
+	// interceptors that are both server and client side so remove interceptors
+	// that are both server and client side when generating the client.
+	if !server {
+		names := make(map[string]struct{}, len(svc.ServerInterceptors))
+		for _, sin := range svc.ServerInterceptors {
+			names[sin.Name] = struct{}{}
 		}
-		for _, intr := range svc.ClientInterceptors {
-			if _, ok := serverInterceptors[intr.Name]; ok {
-				continue
+		filtered := make([]*InterceptorData, 0, len(interceptors))
+		for _, in := range interceptors {
+			if _, ok := names[in.Name]; !ok {
+				filtered = append(filtered, in)
 			}
-			data = append(data, intr)
 		}
+		interceptors = filtered
 	}
 
 	sections := []*codegen.SectionTemplate{
@@ -66,45 +72,59 @@ func interceptorFile(svc *Data, server bool) *codegen.File {
 			codegen.GoaImport(""),
 		}),
 		{
-			Name:   "section" + "-struct",
+			Name:   section,
 			Source: readTemplate(template),
 			Data:   svc,
 		},
 	}
-	if len(data) > 0 {
+	if len(interceptors) > 0 {
 		sections = append(sections, &codegen.SectionTemplate{
-			Name:   section,
-			Source: readTemplate("interceptors"),
-			Data:   data,
+			Name:   "interceptor-types",
+			Source: readTemplate("interceptors_types"),
+			Data:   interceptors,
 			FuncMap: map[string]any{
 				"hasPrivateImplementationTypes": hasPrivateImplementationTypes,
 			},
 		})
 	}
 
-	// Add wrapper sections for each method that has interceptors
+	template = "endpoint_wrappers"
+	section = "endpoint-wrapper"
+	if !server {
+		template = "client_wrappers"
+		section = "client-wrapper"
+	}
 	for _, m := range svc.Methods {
-		if server && len(m.ServerInterceptors) == 0 || !server && len(m.ClientInterceptors) == 0 {
-			continue
-		}
-		template := "endpoint_wrappers"
-		templateName := "endpoint-wrapper"
+		ints := m.ServerInterceptors
 		if !server {
-			template = "client_wrappers"
-			templateName = "client-wrapper"
+			ints = m.ClientInterceptors
+		}
+		if len(ints) == 0 {
+			continue
 		}
 		sections = append(sections, &codegen.SectionTemplate{
-			Name:   templateName,
+			Name:   section,
 			Source: readTemplate(template),
 			Data: map[string]interface{}{
-				"MethodVarName":      codegen.Goify(m.Name, true),
-				"Method":             m.Name,
-				"Service":            svc.Name,
-				"ServerInterceptors": m.ServerInterceptors,
-				"ClientInterceptors": m.ClientInterceptors,
+				"MethodVarName": m.VarName,
+				"Method":        m.Name,
+				"Service":       svc.Name,
+				"Interceptors":  ints,
 			},
 		})
 	}
+
+	if len(interceptors) > 0 {
+		sections = append(sections, &codegen.SectionTemplate{
+			Name:   "interceptors",
+			Source: readTemplate("interceptors"),
+			Data:   interceptors,
+			FuncMap: map[string]any{
+				"hasPrivateImplementationTypes": hasPrivateImplementationTypes,
+			},
+		})
+	}
+
 	return &codegen.File{Path: path, SectionTemplates: sections}
 }
 

codegen/service/interceptors.md

@@ -0,0 +1,149 @@
+# Interceptors Code Generation
+
+Goa generates interceptor code to enable request/response interception and payload/result access. 
+
+---
+
+## 1. Client & Server Interceptors
+
+### Where They Are Generated
+
+Client and server interceptor code is generated in:
+
+- `gen/client_interceptors.go`
+- `gen/service_interceptors.go`
+
+### Templates Used
+
+1. **`server_interceptors.go.tpl`** and **`client_interceptors.go.tpl`**  
+   Define the server and client interceptor interface types.
+   Each template takes a `Data` struct as input.
+
+2. **`interceptors.go.tpl`**  
+   Generates the payload/result access interfaces and accompanying info structs.
+   This template takes a slice of `InterceptorData` as input.
+
+3. **`client_wrappers.go.tpl`** and **`endpoint_wrappers.go.tpl`**  
+   Generate code that wraps client and service endpoints with interceptor callbacks.
+   Each template takes a map with:
+   ```go
+   map[string]any{
+   	"MethodVarName": <Implemented method name>
+		"Method":        <Design method name>
+		"Service":       <Service name>
+		"Interceptors":  <Slice of InterceptorData>
+   }
+   ```
+
+---
+
+## 2. Client & Server Endpoint Wrapper Code
+
+### Where It Is Generated
+
+Endpoint wrapper code for both client and server interceptors is generated in:
+
+- `gen/interceptor_wrappers.go`
+
+### Templates Used
+
+1. **`server_interceptor_wrappers.go.tpl`**  
+   Generates server-specific wrapper implementations. This template receives a map with:
+   ```go
+   map[string]any{
+     "Service":            svc.Name,
+     "ServerInterceptors": svc.ServerInterceptors,
+   }
+   ```
+
+2. **`client_interceptor_wrappers.go.tpl`**  
+   Generates client-specific wrapper implementations. This template receives a map with:
+   ```go
+   map[string]any{
+     "Service":            svc.Name,
+     "ClientInterceptors": svc.ClientInterceptors,
+   }
+   ```
+
+## 3. Example Interceptors
+
+### Where They Are Generated
+
+Example interceptors are generated by the example command in an interceptors sub-package of the user’s service package:
+
+* Client interceptors: `<service>_client.go`
+* Server interceptors: `<service>_server.go`
+
+### Templates Used
+
+1. **`example_client_interceptor.go.tpl` and `example_server_interceptor.go.tpl`**  
+   Generate example interceptor implementations. Each template takes a map with:
+   ```go
+   map[string]any{
+     "StructName":         <interceptor struct name>
+     "ServiceName":        <service name>
+     "PkgName":            <interceptors package name>
+     "ServerInterceptors": <server interceptors slice>
+     "ClientInterceptors": <client interceptors slice>
+   }
+   ```
+
+2. **`example_service_init.go.tpl`**  
+   Generates an example service implementation. This template takes a Data struct.
+
+### Generated Example Features
+
+The example interceptors demonstrate common interception patterns:
+
+* Logging of request/response data
+* Error handling and error logging
+* Type-safe payload and result access through the generated info structs
+* Context propagation across requests and responses
+
+## 4. Data Structures
+
+The templates above share a common set of data structures that describe
+interceptor behavior, payload, result access, and streaming. These data
+structures are defined as follows:
+
+### `Data`
+
+A service-level structure containing information for both client and server interceptors:
+
+* `ServerInterceptors`: A slice of InterceptorData for server-side interceptors
+* `ClientInterceptors`: A slice of InterceptorData for client-side interceptors
+
+### `InterceptorData`
+
+The main structure describing each interceptor’s metadata and requirements:
+
+* `Name`: Generated Go name of the interceptor (CamelCase)
+* `DesignName`: Original name from the design
+* `Description`: Interceptor description from the design
+* `HasPayloadAccess`: Indicates if any method requires payload access
+* `HasResultAccess`: Indicates if any method requires result access
+* `ReadPayload`: List of readable payload fields ([]AttributeData)
+* `WritePayload`: List of writable payload fields ([]AttributeData)
+* `ReadResult`: List of readable result fields ([]AttributeData)
+* `WriteResult`: List of writable result fields ([]AttributeData)
+* `Methods`: A list of MethodInterceptorData containing method-specific interceptor information
+* `ServerStreamInputStruct`: Server stream variable name (used if streaming)
+* `ClientStreamInputStruct`: Client stream variable name (used if streaming)
+
+### `MethodInterceptorData`
+
+Stores per-method interceptor configuration:
+
+* `MethodName`: The method’s Go variable name
+* `PayloadAccess`: Name of the payload access type
+* `ResultAccess`: Name of the result access type
+* `PayloadRef`: Reference to the method's payload type
+* `ResultRef`: Reference to the method's result type
+
+### `AttributeData`
+
+Represents per-field access configuration:
+
+* `Name`: The field accessor method name
+* `TypeRef`: Go type reference for the field
+* `Type`: Underlying attribute type information