fix: add TypeHint-aware parameter binding and styling for []byte (#97)

When an OpenAPI spec uses type: string, format: byte, oapi-codegen
generates a []byte field. Previously the runtime treated []byte as a
generic []uint8 slice -- splitting on commas and parsing individual
integers -- instead of base64 encoding/decoding.

This adds a TypeHint mechanism via new WithOptions variants of existing
functions. Existing functions delegate to the new variants with
zero-value options, preserving all current behavior. Only when
TypeHintBinary is explicitly passed does base64 handling activate.

Encoding uses base64.StdEncoding (standard alphabet, padded) per
OpenAPI 3.0 reference to RFC 4648 Section 4.

Decoding is lenient: it inspects the input to select the correct
decoder rather than blindly cascading (which could corrupt data when
RawStdEncoding silently accepts padded input and treats '=' as data).
If '=' padding is present, it uses the padded decoder; otherwise the
raw (unpadded) decoder. If URL-safe characters ('-' or '_') are
present, it uses the URL-safe alphabet; otherwise the standard
alphabet. This accommodates real-world clients that may send unpadded
or URL-safe base64, while still being correct for spec-compliant
padded standard base64.

New public API:
  - TypeHint, TypeHintNone, TypeHintBinary
  - BindStringToObjectOptions / BindStringToObjectWithOptions
  - StyleParamOptions / StyleParamWithOptions
  - BindQueryParameterOptions / BindQueryParameterWithOptions
  - BindStyledParameterOptions.TypeHint field

The oapi-codegen code generator must be updated separately to emit
calls to these new WithOptions functions with TypeHintBinary for
format: byte fields. Until then, generated code continues to use the
existing functions with unchanged behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mromaszewicz

bindparam.go

@@ -63,6 +63,9 @@ type BindStyledParameterOptions struct {
 	Explode bool
 	// Whether the parameter is required in the query
 	Required bool
+	// TypeHint provides additional type information. When set to TypeHintBinary,
+	// []byte destinations are base64-decoded rather than treated as generic slices.
+	TypeHint TypeHint
 }
 
 // BindStyledParameterWithOptions binds a parameter as described in the Path Parameters
@@ -121,6 +124,22 @@ func BindStyledParameterWithOptions(style string, paramName string, value string
 	}
 
 	if t.Kind() == reflect.Slice {
+		if opts.TypeHint == TypeHintBinary && isByteSlice(t) {
+			parts, err := splitStyledParameter(style, opts.Explode, false, paramName, value)
+			if err != nil {
+				return fmt.Errorf("error splitting input '%s' into parts: %w", value, err)
+			}
+			if len(parts) != 1 {
+				return fmt.Errorf("expected single base64 value for byte slice parameter '%s', got %d parts", paramName, len(parts))
+			}
+			decoded, err := base64Decode(parts[0])
+			if err != nil {
+				return fmt.Errorf("error decoding base64 parameter '%s': %w", paramName, err)
+			}
+			v.SetBytes(decoded)
+			return nil
+		}
+
 		// Chop up the parameter into parts based on its style
 		parts, err := splitStyledParameter(style, opts.Explode, false, paramName, value)
 		if err != nil {
@@ -308,6 +327,19 @@ func bindSplitPartsToDestinationStruct(paramName string, parts []string, explode
 // the Content parameter form.
 func BindQueryParameter(style string, explode bool, required bool, paramName string,
 	queryParams url.Values, dest interface{}) error {
+	return BindQueryParameterWithOptions(style, explode, required, paramName, queryParams, dest, BindQueryParameterOptions{})
+}
+
+// BindQueryParameterOptions defines optional arguments for BindQueryParameterWithOptions.
+type BindQueryParameterOptions struct {
+	// TypeHint provides additional type information. When set to TypeHintBinary,
+	// []byte destinations are base64-decoded rather than treated as generic slices.
+	TypeHint TypeHint
+}
+
+// BindQueryParameterWithOptions works like BindQueryParameter with additional options.
+func BindQueryParameterWithOptions(style string, explode bool, required bool, paramName string,
+	queryParams url.Values, dest interface{}, opts BindQueryParameterOptions) error {
 
 	// dv = destination value.
 	dv := reflect.Indirect(reflect.ValueOf(dest))
@@ -378,7 +410,18 @@ func BindQueryParameter(style string, explode bool, required bool, paramName str
 						return nil
 					}
 				}
-				err = bindSplitPartsToDestinationArray(values, output)
+				if opts.TypeHint == TypeHintBinary && isByteSlice(t) {
+					if len(values) != 1 {
+						return fmt.Errorf("expected single base64 value for byte slice parameter '%s', got %d values", paramName, len(values))
+					}
+					decoded, decErr := base64Decode(values[0])
+					if decErr != nil {
+						return fmt.Errorf("error decoding base64 parameter '%s': %w", paramName, decErr)
+					}
+					v.SetBytes(decoded)
+				} else {
+					err = bindSplitPartsToDestinationArray(values, output)
+				}
 			case reflect.Struct:
 				// This case is really annoying, and error prone, but the
 				// form style object binding doesn't tell us which arguments
@@ -442,7 +485,18 @@ func BindQueryParameter(style string, explode bool, required bool, paramName str
 		var err error
 		switch k {
 		case reflect.Slice:
-			err = bindSplitPartsToDestinationArray(parts, output)
+			if opts.TypeHint == TypeHintBinary && isByteSlice(t) {
+				// For non-exploded form, the value was split on commas above.
+				// Rejoin to get the original base64 string.
+				raw := strings.Join(parts, ",")
+				decoded, decErr := base64Decode(raw)
+				if decErr != nil {
+					return fmt.Errorf("error decoding base64 parameter '%s': %w", paramName, decErr)
+				}
+				v.SetBytes(decoded)
+			} else {
+				err = bindSplitPartsToDestinationArray(parts, output)
+			}
 		case reflect.Struct:
 			err = bindSplitPartsToDestinationStruct(paramName, parts, explode, output)
 		default:

bindparam_test.go

@@ -27,6 +27,94 @@ import (
 	"github.com/oapi-codegen/runtime/types"
 )
 
+// TestBindStyledParameter_ByteSlice tests that BindStyledParameterWithOptions
+// correctly handles *[]byte destinations by base64-decoding the parameter value,
+// rather than treating []byte as a generic slice and splitting on commas.
+// See: https://github.com/oapi-codegen/runtime/issues/97
+func TestBindStyledParameter_ByteSlice(t *testing.T) {
+	expected := []byte("test")
+
+	tests := []struct {
+		name    string
+		style   string
+		explode bool
+		value   string
+	}{
+		{"simple/no-explode", "simple", false, "dGVzdA=="},
+		{"simple/explode", "simple", true, "dGVzdA=="},
+		{"label/no-explode", "label", false, ".dGVzdA=="},
+		{"label/explode", "label", true, ".dGVzdA=="},
+		{"matrix/no-explode", "matrix", false, ";data=dGVzdA=="},
+		{"matrix/explode", "matrix", true, ";data=dGVzdA=="},
+		{"form/no-explode", "form", false, "data=dGVzdA=="},
+		{"form/explode", "form", true, "data=dGVzdA=="},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			var dest []byte
+			err := BindStyledParameterWithOptions(tc.style, "data", tc.value, &dest, BindStyledParameterOptions{
+				ParamLocation: ParamLocationUndefined,
+				Explode:       tc.explode,
+				Required:      true,
+				TypeHint:      TypeHintBinary,
+			})
+			require.NoError(t, err)
+			assert.Equal(t, expected, dest)
+		})
+	}
+}
+
+// TestBindQueryParameter_ByteSlice tests that BindQueryParameter correctly
+// handles *[]byte destinations by base64-decoding the query parameter value.
+// See: https://github.com/oapi-codegen/runtime/issues/97
+func TestBindQueryParameter_ByteSlice(t *testing.T) {
+	expected := []byte("test")
+
+	opts := BindQueryParameterOptions{TypeHint: TypeHintBinary}
+
+	t.Run("form/explode/required", func(t *testing.T) {
+		var dest []byte
+		queryParams := url.Values{"data": {"dGVzdA=="}}
+		err := BindQueryParameterWithOptions("form", true, true, "data", queryParams, &dest, opts)
+		require.NoError(t, err)
+		assert.Equal(t, expected, dest)
+	})
+
+	t.Run("form/no-explode/required", func(t *testing.T) {
+		var dest []byte
+		queryParams := url.Values{"data": {"dGVzdA=="}}
+		err := BindQueryParameterWithOptions("form", false, true, "data", queryParams, &dest, opts)
+		require.NoError(t, err)
+		assert.Equal(t, expected, dest)
+	})
+
+	t.Run("form/explode/optional/present", func(t *testing.T) {
+		var dest *[]byte
+		queryParams := url.Values{"data": {"dGVzdA=="}}
+		err := BindQueryParameterWithOptions("form", true, false, "data", queryParams, &dest, opts)
+		require.NoError(t, err)
+		require.NotNil(t, dest)
+		assert.Equal(t, expected, *dest)
+	})
+
+	t.Run("form/explode/optional/absent", func(t *testing.T) {
+		var dest *[]byte
+		queryParams := url.Values{}
+		err := BindQueryParameterWithOptions("form", true, false, "data", queryParams, &dest, opts)
+		require.NoError(t, err)
+		assert.Nil(t, dest)
+	})
+
+	t.Run("form/explode/optional/empty", func(t *testing.T) {
+		var dest []byte
+		queryParams := url.Values{"data": {""}}
+		err := BindQueryParameterWithOptions("form", true, false, "data", queryParams, &dest, opts)
+		require.NoError(t, err)
+		assert.Equal(t, []byte{}, dest)
+	})
+}
+
 // MockBinder is just an independent version of Binder that has the Bind implemented
 type MockBinder struct {
 	time.Time

bindstring.go

@@ -31,6 +31,19 @@ import (
 // know the destination type each place that we use this, is to generate code
 // to read each specific type.
 func BindStringToObject(src string, dst interface{}) error {
+	return BindStringToObjectWithOptions(src, dst, BindStringToObjectOptions{})
+}
+
+// BindStringToObjectOptions defines optional arguments for BindStringToObjectWithOptions.
+type BindStringToObjectOptions struct {
+	// TypeHint provides additional type information. When set to TypeHintBinary,
+	// []byte destinations are base64-decoded rather than failing.
+	TypeHint TypeHint
+}
+
+// BindStringToObjectWithOptions takes a string, and attempts to assign it to the destination
+// interface via whatever type conversion is necessary, with additional options.
+func BindStringToObjectWithOptions(src string, dst interface{}, opts BindStringToObjectOptions) error {
 	var err error
 
 	v := reflect.ValueOf(dst)
@@ -59,6 +72,17 @@ func BindStringToObject(src string, dst interface{}) error {
 	}
 
 	switch t.Kind() {
+	case reflect.Slice:
+		if opts.TypeHint == TypeHintBinary && isByteSlice(t) {
+			decoded, decErr := base64Decode(src)
+			if decErr != nil {
+				return fmt.Errorf("error binding string parameter: %w", decErr)
+			}
+			v.SetBytes(decoded)
+			return nil
+		}
+		// Non-binary slices fall through to the default error case.
+		fallthrough
 	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
 		var val int64
 		val, err = strconv.ParseInt(src, 10, 64)

bindstring_test.go

@@ -14,12 +14,14 @@
 package runtime
 
 import (
+	"encoding/base64"
 	"fmt"
 	"math"
 	"testing"
 	"time"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 
 	"github.com/oapi-codegen/runtime/types"
 )
@@ -210,3 +212,49 @@ func TestBindStringToObject(t *testing.T) {
 	assert.Equal(t, dstUUID.String(), uuidString)
 
 }
+
+// TestBindStringToObject_ByteSlice tests that BindStringToObject correctly handles
+// *[]byte destinations by base64-decoding the input string, rather than failing
+// or treating []byte as a generic slice.
+// See: https://github.com/oapi-codegen/runtime/issues/97
+func TestBindStringToObject_ByteSlice(t *testing.T) {
+	opts := BindStringToObjectOptions{TypeHint: TypeHintBinary}
+
+	t.Run("valid base64 with padding", func(t *testing.T) {
+		var dest []byte
+		err := BindStringToObjectWithOptions("dGVzdA==", &dest, opts)
+		require.NoError(t, err)
+		assert.Equal(t, []byte("test"), dest)
+	})
+
+	t.Run("valid base64 without padding", func(t *testing.T) {
+		var dest []byte
+		err := BindStringToObjectWithOptions("dGVzdA", &dest, opts)
+		require.NoError(t, err)
+		assert.Equal(t, []byte("test"), dest)
+	})
+
+	t.Run("URL-safe base64", func(t *testing.T) {
+		// "<<??>>+" in standard base64 is "PDw/Pz4+" but URL-safe uses "PDw_Pz4-"
+		input := "PDw_Pz4-"
+		var dest []byte
+		err := BindStringToObjectWithOptions(input, &dest, opts)
+		require.NoError(t, err)
+		expected, decErr := base64.RawURLEncoding.DecodeString("PDw_Pz4-")
+		require.NoError(t, decErr)
+		assert.Equal(t, expected, dest)
+	})
+
+	t.Run("empty string", func(t *testing.T) {
+		var dest []byte
+		err := BindStringToObjectWithOptions("", &dest, opts)
+		require.NoError(t, err)
+		assert.Equal(t, []byte{}, dest)
+	})
+
+	t.Run("invalid base64", func(t *testing.T) {
+		var dest []byte
+		err := BindStringToObjectWithOptions("!!!not-base64!!!", &dest, opts)
+		assert.Error(t, err)
+	})
+}

styleparam.go

@@ -16,6 +16,7 @@ package runtime
 import (
 	"bytes"
 	"encoding"
+	"encoding/base64"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -51,10 +52,27 @@ func StyleParam(style string, explode bool, paramName string, value interface{})
 	return StyleParamWithLocation(style, explode, paramName, ParamLocationUndefined, value)
 }
 
-// Given an input value, such as a primitive type, array or object, turn it
-// into a parameter based on style/explode definition, performing whatever
-// escaping is necessary based on parameter location
+// StyleParamWithLocation serializes a Go value into an OpenAPI-styled parameter
+// string, performing escaping based on parameter location.
 func StyleParamWithLocation(style string, explode bool, paramName string, paramLocation ParamLocation, value interface{}) (string, error) {
+	return StyleParamWithOptions(style, explode, paramName, value, StyleParamOptions{
+		ParamLocation: paramLocation,
+	})
+}
+
+// StyleParamOptions defines optional arguments for StyleParamWithOptions.
+type StyleParamOptions struct {
+	// ParamLocation controls URL escaping behavior.
+	ParamLocation ParamLocation
+	// TypeHint provides additional type information. When set to TypeHintBinary,
+	// []byte values are base64-encoded as a single string rather than treated
+	// as a generic slice of uint8.
+	TypeHint TypeHint
+}
+
+// StyleParamWithOptions serializes a Go value into an OpenAPI-styled parameter
+// string with additional options.
+func StyleParamWithOptions(style string, explode bool, paramName string, value interface{}, opts StyleParamOptions) (string, error) {
 	t := reflect.TypeOf(value)
 	v := reflect.ValueOf(value)
 
@@ -83,24 +101,28 @@ func StyleParamWithLocation(style string, explode bool, paramName string, paramL
 				return "", fmt.Errorf("error marshaling '%s' as text: %w", value, err)
 			}
 
-			return stylePrimitive(style, explode, paramName, paramLocation, string(b))
+			return stylePrimitive(style, explode, paramName, opts.ParamLocation, string(b))
 		}
 	}
 
 	switch t.Kind() {
 	case reflect.Slice:
+		if opts.TypeHint == TypeHintBinary && isByteSlice(t) {
+			encoded := base64.StdEncoding.EncodeToString(v.Bytes())
+			return stylePrimitive(style, explode, paramName, opts.ParamLocation, encoded)
+		}
 		n := v.Len()
 		sliceVal := make([]interface{}, n)
 		for i := 0; i < n; i++ {
 			sliceVal[i] = v.Index(i).Interface()
 		}
-		return styleSlice(style, explode, paramName, paramLocation, sliceVal)
+		return styleSlice(style, explode, paramName, opts.ParamLocation, sliceVal)
 	case reflect.Struct:
-		return styleStruct(style, explode, paramName, paramLocation, value)
+		return styleStruct(style, explode, paramName, opts.ParamLocation, value)
 	case reflect.Map:
-		return styleMap(style, explode, paramName, paramLocation, value)
+		return styleMap(style, explode, paramName, opts.ParamLocation, value)
 	default:
-		return stylePrimitive(style, explode, paramName, paramLocation, value)
+		return stylePrimitive(style, explode, paramName, opts.ParamLocation, value)
 	}
 }