Add typed path segment types for compile-time URL construction safety

Introduce 21 domain-specific string types (Index, Indices, Action,
DocumentID, Alias, Repo, Snapshot, NodeID, Plugin, Policy, Block,
Prefix, Suffix, Name, Resource, Attr, Value, Metric, IndexMetric,
Metrics, NodeFilter) and 25 struct-per-shape path builders that
prevent the double-slash URL bug (#617, #650) at the type level.

Published API types in opensearchapi/ and plugins/ remain string/
[]string — casts to domain types happen internally in GetRequest()
methods, preserving backward compatibility.

Fixes #617, Fixes #650

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

CHANGELOG.md

@@ -14,6 +14,11 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Enhanced cluster readiness checking for improved test reliability: `testutil.NewClient()` now includes readiness validation (health + cluster state + nodes info)
 - Test parallelization support via TEST_PARALLEL environment variable (default: CPU cores - 1, minimum 1)
 - opensearchapi/testutil package with test suite, client helpers, and JSON comparison utilities
+- Add typed path segment types and struct-per-shape path builders for compile-time URL construction safety ([#617](https://github.com/opensearch-project/opensearch-go/issues/617), [#650](https://github.com/opensearch-project/opensearch-go/issues/650))
+  - Domain types: `Index`, `Indices`, `Action`, `DocumentID`, `Alias`, `Repo`, `Snapshot`, `NodeID`, `Plugin`, `Policy`, `Block`, `Prefix`, `Suffix`, `Name`, `Resource`, `Attr`, `Value`, `Metric`, `IndexMetric`, `Metrics`, `NodeFilter`
+  - 25 path builder structs: `IndexPath`, `DocumentPath`, `IndicesActionPath`, `AliasPath`, `SnapshotPath`, `NodesPath`, `PluginResourcePath`, `PrefixActionPath`, `ActionSuffixPath`, etc.
+  - `ToIndices([]string)` and `MustBuild()` helpers
+  - Published API types in `opensearchapi/` and `plugins/` remain `string`/`[]string`; casts to domain types happen internally in `GetRequest()` methods
 - opensearchtransport/testutil package with PollUntil helper for eventual consistency testing (ISM policies, index readiness, cluster state changes)
 - Configuration option `IncludeDedicatedClusterManagers` for controlling cluster manager node routing ([#765](https://github.com/opensearch-project/opensearch-go/issues/765))
 - Policy-based routing system for improved request routing and service availability ([#771](https://github.com/opensearch-project/opensearch-go/pull/771))
@@ -146,6 +151,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Fixed
 
 - Skip shard routing integration tests on OpenSearch < 2.2.0 with security plugin due to server-side `OptionalDataException` from non-thread-safe User serialization (opensearch-project/security#1970)
+- Fix URL path construction across 74 `GetRequest` methods where empty path segments produced a double-slash `//` that `http.NewRequest` misparsed as an RFC 3986 authority separator; replace manual `strings.Builder` paths with typed path builder structs that reject empty required segments ([#617](https://github.com/opensearch-project/opensearch-go/issues/617), [#650](https://github.com/opensearch-project/opensearch-go/issues/650))
 - Fix alias, mapping, settings, and block API URL path construction when Indices is empty, which caused `http.NewRequest` to misparse the double-slash as an authority separator ([#650](https://github.com/opensearch-project/opensearch-go/issues/650))
 - Fix URL path construction across 74 `GetRequest` methods where empty path segments produced a double-slash `//` that `http.NewRequest` misparsed as an RFC 3986 authority separator; extract `opensearch.BuildPath` helper to prevent the class of bug ([#617](https://github.com/opensearch-project/opensearch-go/issues/617), [#650](https://github.com/opensearch-project/opensearch-go/issues/650))
 - Fix flaky `TestDefaultHealthCheck_RetryAfterMaxRetry`: replace wall-clock `time.Sleep` + `atomic.Int64` synchronization with context cancellation (`ctx.Done()`), and widen `maxRetryClusterHealth` to 5s so the baseline HTTP round-trip cannot race past the retry interval ([#787](https://github.com/opensearch-project/opensearch-go/pull/787))

opensearchapi/api_bulk.go

@@ -10,7 +10,6 @@ import (
 	"context"
 	"io"
 	"net/http"
-	"strings"
 
 	"github.com/opensearch-project/opensearch-go/v4"
 )
@@ -38,24 +37,11 @@ type BulkReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r BulkReq) GetRequest() (*http.Request, error) {
-	var path strings.Builder
-	//nolint:mnd // 7 is the max number of static chars
-	path.Grow(7 + len(r.Index))
-
-	if len(r.Index) > 0 {
-		path.WriteString("/")
-		path.WriteString(r.Index)
+	path, err := opensearch.PrefixActionPath{Prefix: opensearch.Prefix(r.Index), Action: "_bulk"}.Build()
+	if err != nil {
+		return nil, err
 	}
-
-	path.WriteString("/_bulk")
-
-	return opensearch.BuildRequest(
-		"POST",
-		path.String(),
-		r.Body,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodPost, path, r.Body, r.Params.get(), r.Header)
 }
 
 // BulkResp represents the returned struct of the /_bulk response

opensearchapi/api_cat-aliases.go

@@ -22,21 +22,11 @@ type CatAliasesReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r CatAliasesReq) GetRequest() (*http.Request, error) {
-	aliases := strings.Join(r.Aliases, ",")
-	var path strings.Builder
-	path.Grow(len("/_cat/aliases/") + len(aliases))
-	path.WriteString("/_cat/aliases")
-	if len(r.Aliases) > 0 {
-		path.WriteString("/")
-		path.WriteString(aliases)
+	path, err := opensearch.ActionSuffixPath{Action: "_cat/aliases", Suffix: opensearch.Suffix(strings.Join(r.Aliases, ","))}.Build()
+	if err != nil {
+		return nil, err
 	}
-	return opensearch.BuildRequest(
-		"GET",
-		path.String(),
-		nil,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodGet, path, nil, r.Params.get(), r.Header)
 }
 
 // CatAliasesResp represents the returned struct of the /_cat/aliases response

opensearchapi/api_cat-allocation.go

@@ -22,21 +22,11 @@ type CatAllocationReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r CatAllocationReq) GetRequest() (*http.Request, error) {
-	nodes := strings.Join(r.NodeIDs, ",")
-	var path strings.Builder
-	path.Grow(len("/_cat/allocation/") + len(nodes))
-	path.WriteString("/_cat/allocation")
-	if len(r.NodeIDs) > 0 {
-		path.WriteString("/")
-		path.WriteString(nodes)
+	path, err := opensearch.ActionSuffixPath{Action: "_cat/allocation", Suffix: opensearch.Suffix(strings.Join(r.NodeIDs, ","))}.Build()
+	if err != nil {
+		return nil, err
 	}
-	return opensearch.BuildRequest(
-		"GET",
-		path.String(),
-		nil,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodGet, path, nil, r.Params.get(), r.Header)
 }
 
 // CatAllocationsResp represents the returned struct of the /_cat/allocation response

opensearchapi/api_cat-count.go

@@ -22,21 +22,11 @@ type CatCountReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r CatCountReq) GetRequest() (*http.Request, error) {
-	indices := strings.Join(r.Indices, ",")
-	var path strings.Builder
-	path.Grow(len("/_cat/count/") + len(indices))
-	path.WriteString("/_cat/count")
-	if len(r.Indices) > 0 {
-		path.WriteString("/")
-		path.WriteString(indices)
+	path, err := opensearch.ActionSuffixPath{Action: "_cat/count", Suffix: opensearch.Suffix(strings.Join(r.Indices, ","))}.Build()
+	if err != nil {
+		return nil, err
 	}
-	return opensearch.BuildRequest(
-		"GET",
-		path.String(),
-		nil,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodGet, path, nil, r.Params.get(), r.Header)
 }
 
 // CatCountsResp represents the returned struct of the /_cat/count response

opensearchapi/api_cat-fielddata.go

@@ -22,21 +22,11 @@ type CatFieldDataReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r CatFieldDataReq) GetRequest() (*http.Request, error) {
-	fielddata := strings.Join(r.FieldData, ",")
-	var path strings.Builder
-	path.Grow(len("/_cat/fielddata/") + len(fielddata))
-	path.WriteString("/_cat/fielddata")
-	if len(r.FieldData) > 0 {
-		path.WriteString("/")
-		path.WriteString(fielddata)
+	path, err := opensearch.ActionSuffixPath{Action: "_cat/fielddata", Suffix: opensearch.Suffix(strings.Join(r.FieldData, ","))}.Build()
+	if err != nil {
+		return nil, err
 	}
-	return opensearch.BuildRequest(
-		"GET",
-		path.String(),
-		nil,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodGet, path, nil, r.Params.get(), r.Header)
 }
 
 // CatFieldDataResp represents the returned struct of the /_cat/fielddata response

opensearchapi/api_cat-indices.go

@@ -22,21 +22,11 @@ type CatIndicesReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r CatIndicesReq) GetRequest() (*http.Request, error) {
-	indices := strings.Join(r.Indices, ",")
-	var path strings.Builder
-	path.Grow(len("/_cat/indices/") + len(indices))
-	path.WriteString("/_cat/indices")
-	if len(r.Indices) > 0 {
-		path.WriteString("/")
-		path.WriteString(indices)
+	path, err := opensearch.ActionSuffixPath{Action: "_cat/indices", Suffix: opensearch.Suffix(strings.Join(r.Indices, ","))}.Build()
+	if err != nil {
+		return nil, err
 	}
-	return opensearch.BuildRequest(
-		"GET",
-		path.String(),
-		nil,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodGet, path, nil, r.Params.get(), r.Header)
 }
 
 // CatIndicesResp represents the returned struct of the /_cat/indices response

opensearchapi/api_cat-recovery.go

@@ -22,21 +22,11 @@ type CatRecoveryReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r CatRecoveryReq) GetRequest() (*http.Request, error) {
-	indices := strings.Join(r.Indices, ",")
-	var path strings.Builder
-	path.Grow(len("/_cat/recovery/") + len(indices))
-	path.WriteString("/_cat/recovery")
-	if len(r.Indices) > 0 {
-		path.WriteString("/")
-		path.WriteString(indices)
+	path, err := opensearch.ActionSuffixPath{Action: "_cat/recovery", Suffix: opensearch.Suffix(strings.Join(r.Indices, ","))}.Build()
+	if err != nil {
+		return nil, err
 	}
-	return opensearch.BuildRequest(
-		"GET",
-		path.String(),
-		nil,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodGet, path, nil, r.Params.get(), r.Header)
 }
 
 // CatRecoveryResp represents the returned struct of the /_cat/recovery response

opensearchapi/api_cat-segments.go

@@ -22,21 +22,11 @@ type CatSegmentsReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r CatSegmentsReq) GetRequest() (*http.Request, error) {
-	indices := strings.Join(r.Indices, ",")
-	var path strings.Builder
-	path.Grow(len("/_cat/segments/") + len(indices))
-	path.WriteString("/_cat/segments")
-	if len(r.Indices) > 0 {
-		path.WriteString("/")
-		path.WriteString(indices)
+	path, err := opensearch.ActionSuffixPath{Action: "_cat/segments", Suffix: opensearch.Suffix(strings.Join(r.Indices, ","))}.Build()
+	if err != nil {
+		return nil, err
 	}
-	return opensearch.BuildRequest(
-		"GET",
-		path.String(),
-		nil,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodGet, path, nil, r.Params.get(), r.Header)
 }
 
 // CatSegmentsResp represents the returned struct of the /_cat/segments response

opensearchapi/api_cat-shards.go

@@ -22,21 +22,11 @@ type CatShardsReq struct {
 
 // GetRequest returns the *http.Request that gets executed by the client
 func (r CatShardsReq) GetRequest() (*http.Request, error) {
-	indices := strings.Join(r.Indices, ",")
-	var path strings.Builder
-	path.Grow(len("/_cat/shards/") + len(indices))
-	path.WriteString("/_cat/shards")
-	if len(r.Indices) > 0 {
-		path.WriteString("/")
-		path.WriteString(indices)
+	path, err := opensearch.ActionSuffixPath{Action: "_cat/shards", Suffix: opensearch.Suffix(strings.Join(r.Indices, ","))}.Build()
+	if err != nil {
+		return nil, err
 	}
-	return opensearch.BuildRequest(
-		"GET",
-		path.String(),
-		nil,
-		r.Params.get(),
-		r.Header,
-	)
+	return opensearch.BuildRequest(http.MethodGet, path, nil, r.Params.get(), r.Header)
 }
 
 // CatShardsResp represents the returned struct of the /_cat/shards response