feat(remote): add LoggingTransport for slog-based HTTP debug logging (#1190)

## What

Adds `LoggingTransport` and `NewLoggingTransport(inner
http.RoundTripper, logger *slog.Logger) *LoggingTransport` in
`registry/remote`:

- Wraps an `http.RoundTripper` and logs every request/response pair at
`slog.LevelDebug`.
- Defaults: `inner=http.DefaultTransport`, `logger=slog.Default()`.
- Scrubs sensitive headers (`Authorization`, `Set-Cookie`) from logs.
- Clips response bodies at 16 KiB.
- A package-level `atomic.Uint64` counter assigns each pair a sequential
ID so request/response lines can be correlated across concurrent
operations (oras-go does parallel blob fetches, so log lines
interleave).

## Why

Part of the v3 PR-by-PR breakdown (**PR 8:
`feat/remote-transport-utils`**), reduced scope:

- `warning.go` / `warning_test.go` (also part of prs.md PR 8) are
**already merged** to `upstream/main`.
- The `internal/ioutil` clean-up-temp-file fix (the other prs.md PR 8
piece) is already proposed in open PR #1185 (`fix(ioutil): clean up temp
file on Ingest error`), so it's excluded here.

This PR ships only the genuinely new, standalone piece: the
LoggingTransport.

## Test plan

- [x] `go build -mod=mod ./registry/remote/...`
- [x] `go test -mod=mod ./registry/remote/` — passes (`ok ... 21.025s`)
- [x] `go test -mod=mod -run LoggingTransport -v` —
`TestNewLoggingTransport_Defaults`, `TestLoggingTransport_RoundTrip`,
`TestLoggingTransport_RoundTrip_Error` all PASS

Signed-off-by: Terry Howe <terrylhowe@gmail.com>

Author: TerryHowe

registry/remote/logging_transport.go

@@ -0,0 +1,185 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package remote
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"log/slog"
+	"mime"
+	"net/http"
+	"strings"
+	"sync/atomic"
+)
+
+// sensitiveHeaders is the set of headers whose values are scrubbed from logs.
+var sensitiveHeaders = []string{
+	"Authorization",
+	"Set-Cookie",
+}
+
+// loggingPayloadSizeLimit is the maximum number of response body bytes printed.
+const loggingPayloadSizeLimit int64 = 16 * 1024 // 16 KiB
+
+// requestCounter assigns a unique sequential ID to each logged
+// request/response pair. Because oras-go performs concurrent HTTP requests
+// (e.g. parallel blob fetches), the ID lets callers correlate a request log
+// line with its corresponding response log line when output is interleaved.
+var requestCounter atomic.Uint64
+
+// LoggingTransport is an http.RoundTripper that logs every request and its
+// response at slog.LevelDebug. It is safe for concurrent use.
+//
+// Usage:
+//
+//	reg := remote.NewRegistry("example.com")
+//	reg.Client = &auth.Client{
+//	    Client: &http.Client{
+//	        Transport: remote.NewLoggingTransport(http.DefaultTransport, nil),
+//	    },
+//	}
+type LoggingTransport struct {
+	inner  http.RoundTripper
+	logger *slog.Logger
+}
+
+// NewLoggingTransport wraps inner with request/response debug logging.
+// If logger is nil, slog.Default() is used. If inner is nil,
+// http.DefaultTransport is used.
+func NewLoggingTransport(inner http.RoundTripper, logger *slog.Logger) *LoggingTransport {
+	if inner == nil {
+		inner = http.DefaultTransport
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &LoggingTransport{inner: inner, logger: logger}
+}
+
+// RoundTrip implements http.RoundTripper, logging the request and response.
+func (t *LoggingTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	id := requestCounter.Add(1) - 1
+
+	t.logger.Debug(req.Method,
+		"id", id,
+		"url", req.URL,
+		"header", formatHeaders(req.Header),
+	)
+
+	resp, err := t.inner.RoundTrip(req)
+	if err != nil {
+		t.logger.Debug("Response",
+			"id", id,
+			"error", err,
+		)
+		return resp, err
+	}
+
+	t.logger.Debug("Response",
+		"id", id,
+		"status", resp.Status,
+		"header", formatHeaders(resp.Header),
+		"body", formatResponseBody(resp),
+	)
+	return resp, nil
+}
+
+// formatHeaders returns a human-readable representation of the headers with
+// sensitive values (Authorization, Set-Cookie) replaced by "*****".
+func formatHeaders(header http.Header) string {
+	if len(header) == 0 {
+		return "   Empty header"
+	}
+	var parts []string
+	for k, v := range header {
+		val := strings.Join(v, ", ")
+		for _, sensitive := range sensitiveHeaders {
+			if strings.EqualFold(k, sensitive) {
+				val = "*****"
+				break
+			}
+		}
+		parts = append(parts, fmt.Sprintf("   %q: %q", k, val))
+	}
+	return strings.Join(parts, "\n")
+}
+
+// formatResponseBody reads up to loggingPayloadSizeLimit bytes from the
+// response body and returns them as a string, then restores resp.Body so
+// subsequent reads by the caller see the full body. Non-printable content
+// types and bodies containing potential credentials are not printed.
+func formatResponseBody(resp *http.Response) string {
+	if resp.Body == nil || resp.Body == http.NoBody {
+		return "   No response body"
+	}
+
+	contentType := resp.Header.Get("Content-Type")
+	if contentType == "" {
+		return "   Response body without content type not printed"
+	}
+	if !isLoggableContentType(contentType) {
+		return fmt.Sprintf("   Response body of content type %q not printed", contentType)
+	}
+
+	// Read up to the limit into buf, then restore resp.Body by prepending
+	// the already-read bytes ahead of the remaining body.
+	var buf bytes.Buffer
+	if _, err := io.CopyN(&buf, resp.Body, loggingPayloadSizeLimit+1); err != nil && err != io.EOF {
+		return fmt.Sprintf("   Error reading response body: %v", err)
+	}
+
+	// Restore: callers see buf contents followed by any unread remainder.
+	remaining := resp.Body
+	resp.Body = struct {
+		io.Reader
+		io.Closer
+	}{
+		Reader: io.MultiReader(bytes.NewReader(buf.Bytes()), remaining),
+		Closer: remaining,
+	}
+
+	body := buf.String()
+	if len(body) == 0 {
+		return "   Response body is empty"
+	}
+	if containsCredentialFields(body) {
+		return "   Response body redacted (potential credentials)"
+	}
+	if int64(len(body)) > loggingPayloadSizeLimit {
+		return body[:loggingPayloadSizeLimit] + "\n...(truncated)"
+	}
+	return body
+}
+
+// isLoggableContentType returns true for JSON and plain-text content types.
+func isLoggableContentType(contentType string) bool {
+	mediaType, _, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		return false
+	}
+	switch mediaType {
+	case "application/json", "text/plain", "text/html":
+		return true
+	}
+	return strings.HasSuffix(mediaType, "+json")
+}
+
+// containsCredentialFields returns true if the body appears to contain
+// authentication tokens that should not be logged.
+func containsCredentialFields(body string) bool {
+	return strings.Contains(body, `"token"`) || strings.Contains(body, `"access_token"`)
+}

registry/remote/logging_transport_test.go

@@ -0,0 +1,196 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package remote
+
+import (
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// roundTripFunc is an http.RoundTripper backed by a function.
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) { return f(req) }
+
+func TestNewLoggingTransport_Defaults(t *testing.T) {
+	lt := NewLoggingTransport(nil, nil)
+	if lt.inner == nil {
+		t.Error("inner should default to http.DefaultTransport")
+	}
+	if lt.logger == nil {
+		t.Error("logger should default to slog.Default()")
+	}
+}
+
+func TestLoggingTransport_RoundTrip(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"status":"ok"}`))
+	}))
+	defer srv.Close()
+
+	lt := NewLoggingTransport(http.DefaultTransport, slog.Default())
+	req, _ := http.NewRequest(http.MethodGet, srv.URL, nil)
+	resp, err := lt.RoundTrip(req)
+	if err != nil {
+		t.Fatalf("RoundTrip() error = %v", err)
+	}
+	defer resp.Body.Close()
+
+	// Body must still be readable after LoggingTransport consumed it for logging.
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("ReadAll() error = %v", err)
+	}
+	if string(body) != `{"status":"ok"}` {
+		t.Errorf("body = %q, want %q", body, `{"status":"ok"}`)
+	}
+}
+
+func TestLoggingTransport_RoundTrip_Error(t *testing.T) {
+	wantErr := io.ErrUnexpectedEOF
+	inner := roundTripFunc(func(*http.Request) (*http.Response, error) {
+		return nil, wantErr
+	})
+	lt := NewLoggingTransport(inner, slog.Default())
+	req, _ := http.NewRequest(http.MethodGet, "http://example.com", nil)
+	_, err := lt.RoundTrip(req)
+	if err != wantErr {
+		t.Errorf("RoundTrip() error = %v, want %v", err, wantErr)
+	}
+}
+
+func TestFormatHeaders_Scrubbing(t *testing.T) {
+	h := http.Header{
+		"Authorization": {"Bearer secret"},
+		"Content-Type":  {"application/json"},
+		"Set-Cookie":    {"session=abc"},
+	}
+	out := formatHeaders(h)
+	if strings.Contains(out, "secret") {
+		t.Error("Authorization value should be scrubbed")
+	}
+	if strings.Contains(out, "session=abc") {
+		t.Error("Set-Cookie value should be scrubbed")
+	}
+	if !strings.Contains(out, "Content-Type") {
+		t.Error("Content-Type should be present")
+	}
+}
+
+func TestFormatHeaders_Empty(t *testing.T) {
+	out := formatHeaders(http.Header{})
+	if !strings.Contains(out, "Empty") {
+		t.Errorf("expected empty header message, got %q", out)
+	}
+}
+
+func TestFormatResponseBody_NoBody(t *testing.T) {
+	resp := &http.Response{Body: http.NoBody}
+	out := formatResponseBody(resp)
+	if !strings.Contains(out, "No response body") {
+		t.Errorf("got %q", out)
+	}
+}
+
+func TestFormatResponseBody_NonPrintable(t *testing.T) {
+	resp := &http.Response{
+		Header: http.Header{"Content-Type": {"application/octet-stream"}},
+		Body:   io.NopCloser(strings.NewReader("binary")),
+	}
+	out := formatResponseBody(resp)
+	if !strings.Contains(out, "not printed") {
+		t.Errorf("got %q", out)
+	}
+}
+
+func TestFormatResponseBody_CredentialRedaction(t *testing.T) {
+	resp := &http.Response{
+		Header: http.Header{"Content-Type": {"application/json"}},
+		Body:   io.NopCloser(strings.NewReader(`{"token":"secret"}`)),
+	}
+	out := formatResponseBody(resp)
+	if !strings.Contains(out, "redacted") {
+		t.Errorf("got %q", out)
+	}
+}
+
+func TestFormatResponseBody_BodyRestored(t *testing.T) {
+	payload := `{"foo":"bar"}`
+	resp := &http.Response{
+		Header: http.Header{"Content-Type": {"application/json"}},
+		Body:   io.NopCloser(strings.NewReader(payload)),
+	}
+	formatResponseBody(resp)
+
+	// Body must be intact after formatResponseBody reads it.
+	got, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("ReadAll after formatResponseBody: %v", err)
+	}
+	if string(got) != payload {
+		t.Errorf("body after logging = %q, want %q", got, payload)
+	}
+}
+
+func TestFormatResponseBody_Truncated(t *testing.T) {
+	large := strings.Repeat("a", int(loggingPayloadSizeLimit)+100)
+	resp := &http.Response{
+		Header: http.Header{"Content-Type": {"text/plain"}},
+		Body:   io.NopCloser(strings.NewReader(large)),
+	}
+	out := formatResponseBody(resp)
+	if !strings.Contains(out, "truncated") {
+		t.Errorf("expected truncation notice, got %q", out[:50])
+	}
+}
+
+func TestIsLoggableContentType(t *testing.T) {
+	tests := []struct {
+		ct   string
+		want bool
+	}{
+		{"application/json", true},
+		{"application/json; charset=utf-8", true},
+		{"application/vnd.oci.image.manifest.v1+json", true},
+		{"text/plain", true},
+		{"text/html", true},
+		{"application/octet-stream", false},
+		{"", false},
+	}
+	for _, tt := range tests {
+		if got := isLoggableContentType(tt.ct); got != tt.want {
+			t.Errorf("isLoggableContentType(%q) = %v, want %v", tt.ct, got, tt.want)
+		}
+	}
+}
+
+func TestContainsCredentialFields(t *testing.T) {
+	if !containsCredentialFields(`{"token":"x"}`) {
+		t.Error(`expected true for "token"`)
+	}
+	if !containsCredentialFields(`{"access_token":"x"}`) {
+		t.Error(`expected true for "access_token"`)
+	}
+	if containsCredentialFields(`{"status":"ok"}`) {
+		t.Error("expected false for non-credential body")
+	}
+}