feat: add http.WithHeaderComment middleware

.changelog/a33cd9f8b5d5438a8f8140ee4f39c2f7.json

@@ -0,0 +1,8 @@
+{
+ "id": "a33cd9f8-b5d5-438a-8f81-40ee4f39c2f7",
+ "type": "feature",
+ "description": "Add `http.WithHeaderComment` middleware.",
+ "modules": [
+ "."
+ ]
+}

transport/http/middleware_header_comment.go

@@ -0,0 +1,81 @@
+package http
+
+import (
+ "context"
+ "fmt"
+ "net/http"
+
+ "github.com/aws/smithy-go/middleware"
+)
+
+// WithHeaderComment instruments a middleware stack to append an HTTP field
+// comment to the given header as specified in RFC 9110
+// (https://www.rfc-editor.org/rfc/rfc9110#name-comments).
+//
+// The header is case-insensitive. If the provided header exists when the
+// middleware runs, the content will be inserted as-is enclosed in parentheses.
+//
+// Note that per the HTTP specification, comments are only allowed in fields
+// containing "comment" as part of their field value definition, but this API
+// will NOT verify whether the provided header is one of them.
+//
+// WithHeaderComment MAY be applied more than once to a middleware stack and/or
+// more than once per header.
+func WithHeaderComment(header, content string) func(*middleware.Stack) error {
+ return func(s *middleware.Stack) error {
+ m, err := getOrAddHeaderComment(s)
+ if err != nil {
+ return fmt.Errorf("get or add header comment: %v", err)
+ }
+
+ m.values.Add(header, content)
+ return nil
+ }
+}
+
+type headerCommentMiddleware struct {
+ values http.Header // hijack case-insensitive access APIs
+}
+
+func (*headerCommentMiddleware) ID() string {
+ return "headerComment"
+}
+
+func (m *headerCommentMiddleware) HandleBuild(ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler) (
+ out middleware.BuildOutput, metadata middleware.Metadata, err error,
+) {
+ r, ok := in.Request.(*Request)
+ if !ok {
+ return out, metadata, fmt.Errorf("unknown transport type %T", in.Request)
+ }
+
+ for h, contents := range m.values {
+ for _, c := range contents {
+ if existing := r.Header.Get(h); existing != "" {
+ r.Header.Set(h, fmt.Sprintf("%s (%s)", existing, c))
+ }
+ }
+ }
+
+ return next.HandleBuild(ctx, in)
+}
+
+func getOrAddHeaderComment(s *middleware.Stack) (*headerCommentMiddleware, error) {
+ id := (*headerCommentMiddleware)(nil).ID()
+ m, ok := s.Build.Get(id)
+ if !ok {
+ m := &headerCommentMiddleware{values: http.Header{}}
+ if err := s.Build.Add(m, middleware.After); err != nil {
+ return nil, fmt.Errorf("add build: %v", err)
+ }
+
+ return m, nil
+ }
+
+ hc, ok := m.(*headerCommentMiddleware)
+ if !ok {
+ return nil, fmt.Errorf("existing middleware w/ id %s is not *headerCommentMiddleware", id)
+ }
+
+ return hc, nil
+}

transport/http/middleware_header_comment_test.go

@@ -0,0 +1,113 @@
+package http
+
+import (
+ "context"
+ "net/http"
+ "testing"
+
+ "github.com/aws/smithy-go/middleware"
+)
+
+func TestWithHeaderComment_CaseInsensitive(t *testing.T) {
+ stack, err := newTestStack(
+ WithHeaderComment("foo", "bar"),
+ )
+ if err != nil {
+ t.Errorf("expected no error on new stack, got %v", err)
+ }
+
+ r := injectBuildRequest(stack)
+ r.Header.Set("Foo", "baz")
+
+ if err := handle(stack); err != nil {
+ t.Errorf("expected no error on handle, got %v", err)
+ }
+
+ expectHeader(t, r.Header, "Foo", "baz (bar)")
+}
+
+func TestWithHeaderComment_Noop(t *testing.T) {
+ stack, err := newTestStack(
+ WithHeaderComment("foo", "bar"),
+ )
+ if err != nil {
+ t.Errorf("expected no error on new stack, got %v", err)
+ }
+
+ r := injectBuildRequest(stack)
+
+ if err := handle(stack); err != nil {
+ t.Errorf("expected no error on handle, got %v", err)
+ }
+
+ expectHeader(t, r.Header, "Foo", "")
+}
+
+func TestWithHeaderComment_MultiCaseInsensitive(t *testing.T) {
+ stack, err := newTestStack(
+ WithHeaderComment("foo", "c1"),
+ WithHeaderComment("Foo", "c2"),
+ WithHeaderComment("baz", "c3"),
+ WithHeaderComment("Baz", "c4"),
+ )
+ if err != nil {
+ t.Errorf("expected no error on new stack, got %v", err)
+ }
+
+ r := injectBuildRequest(stack)
+ r.Header.Set("Foo", "1")
+ r.Header.Set("Baz", "2")
+
+ if err := handle(stack); err != nil {
+ t.Errorf("expected no error on handle, got %v", err)
+ }
+
+ expectHeader(t, r.Header, "Foo", "1 (c1) (c2)")
+ expectHeader(t, r.Header, "Baz", "2 (c3) (c4)")
+}
+
+func newTestStack(fns ...func(*middleware.Stack) error) (*middleware.Stack, error) {
+ s := middleware.NewStack("", NewStackRequest)
+ for _, fn := range fns {
+ if err := fn(s); err != nil {
+ return nil, err
+ }
+ }
+ return s, nil
+}
+
+func handle(stack *middleware.Stack) error {
+ _, _, err := middleware.DecorateHandler(
+ middleware.HandlerFunc(
+ func(ctx context.Context, input interface{}) (
+ interface{}, middleware.Metadata, error,
+ ) {
+ return nil, middleware.Metadata{}, nil
+ },
+ ),
+ stack,
+ ).Handle(context.Background(), nil)
+ return err
+}
+
+func injectBuildRequest(s *middleware.Stack) *Request {
+ r := NewStackRequest()
+ s.Build.Add(
+ middleware.BuildMiddlewareFunc(
+ "injectBuildRequest",
+ func(ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler) (
+ middleware.BuildOutput, middleware.Metadata, error,
+ ) {
+ return next.HandleBuild(ctx, middleware.BuildInput{Request: r})
+ },
+ ),
+ middleware.Before,
+ )
+ return r.(*Request)
+}
+
+func expectHeader(t *testing.T, header http.Header, h, ev string) {
+ if av := header.Get(h); ev != av {
+ t.Errorf("expected header '%s: %s', got '%s'", h, ev, av)
+ }
+}