feat(opensearchtransport): add OperationClassifier and bit-packed OperationID

Add a zero-allocation HTTP method+path classifier that reuses the
existing routeTrie to map requests to structured OperationID values.
Enables transparent metrics, tracing, and access-control middleware
at the http.RoundTripper layer without per-operation wrapper code.

OperationID is a bit-packed int64 encoding R/W flag, category, and
minor operation. Masking helpers (IsWrite, Category, Minor) support
efficient bitwise filtering. String() returns Prometheus-friendly
labels.

OperationClassifier is built from the canonical route table and is
safe for concurrent use. Returns OpOther for unrecognized patterns.

Adds OperationID field to trieLeaf/trieMatch, OpID() to the Route
interface, and .Op() to RouteBuilder. All 124 routes are tagged.

Ref: opensearch-project#816

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

Author: sean-

CHANGELOG.md

@@ -99,6 +99,12 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
   - `Config.ReturnQueryErrors` defaults to `false` in v4 (opt-in), will flip to `true` in v5
   - `OPENSEARCH_GO_PARTIAL_QUERY_ERRORS` environment variable overrides `Config.ReturnQueryErrors` at runtime
   - Both `(resp, error)` are non-nil on partial failure -- response is fully populated
+- Add `OperationClassifier` for zero-allocation HTTP method+path to `OperationID` mapping ([#816](https://github.com/opensearch-project/opensearch-go/issues/816))
+  - Bit-packed `OperationID` (int64) encoding R/W flag, category, and minor operation
+  - Masking helpers: `IsWrite`, `IsRead`, `Category`, `Minor`
+  - `String()` returns Prometheus-friendly labels (e.g., `"search"`, `"bulk"`, `"doc_get"`)
+  - Reuses existing `routeTrie` for O(path-segments) lookup, safe for concurrent use
+  - Enables transparent metrics/tracing middleware at the `http.RoundTripper` layer
   - Transport automatically sets `max_concurrent_shard_requests` query parameter on search requests routed through a coordinator node
   - Value derived from a cluster-wide aggregate of all polled nodes' search pool wait-time and completion deltas, clamped to `[floor, cap]` (default: 5–256)
   - Cluster-wide signal correctly models data-node fan-out capacity: single hot nodes are diluted by healthy peers, and MCSR only drops when aggregate cluster pressure rises

USER_GUIDE.md

@@ -457,6 +457,47 @@ Key settings to verify on any custom transport:
 
 `Clone()` copies all of these. If you must build from scratch (e.g. for a non-`*http.Transport` round tripper), set at minimum `ForceAttemptHTTP2: true` and `MaxIdleConnsPerHost` >= your expected concurrency.
 
+## Operation Classifier
+
+The `opensearchtransport.OperationClassifier` maps HTTP method+path pairs to structured `OperationID` values. This enables transparent metrics, tracing, or access-control middleware at the `http.RoundTripper` layer without per-operation wrapper code.
+
+```go
+import "github.com/opensearch-project/opensearch-go/v4/opensearchtransport"
+
+// Build once, reuse across requests. Safe for concurrent use.
+classifier := opensearchtransport.NewOperationClassifier()
+
+// In an http.RoundTripper:
+func (t *MetricsTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+    op := t.classifier.Classify(req.Method, req.URL.Path)
+
+    start := time.Now()
+    resp, err := t.next.RoundTrip(req)
+    duration := time.Since(start)
+
+    status := 0
+    if resp != nil {
+        status = resp.StatusCode
+    }
+    t.histogram.WithLabelValues(op.String(), strconv.Itoa(status)).Observe(
+        float64(duration.Milliseconds()),
+    )
+    return resp, err
+}
+```
+
+`OperationID` is a bit-packed `int64` with masking helpers:
+
+```go
+op := classifier.Classify("POST", "/my-index/_search")
+op.String()     // "search"
+op.IsWrite()    // false
+op.IsRead()     // true
+op.Category()   // CatSearch
+```
+
+Returns `OpOther` for unrecognized patterns.
+
 ## Debugging
 
 Set the `OPENSEARCH_GO_DEBUG` environment variable to enable debug logging for connection management, node discovery, and request routing. Debug output is written to stderr.

opensearchtransport/classify.go

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// The OpenSearch Contributors require contributions made to
+// this file be licensed under the Apache-2.0 license or a
+// compatible open source license.
+//
+// Modifications Copyright OpenSearch Contributors. See
+// GitHub history for details.
+
+// Licensed to Elasticsearch B.V. under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Elasticsearch B.V. licenses this file to you 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 opensearchtransport
+
+// OperationClassifier maps HTTP method+path pairs to [OperationID] values.
+// It reuses the same route trie used by [MuxPolicy], so classification is
+// zero-allocation for well-formed paths.
+//
+// Build once with [NewOperationClassifier] and reuse across requests.
+type OperationClassifier struct {
+	trie routeTrie
+}
+
+// NewOperationClassifier builds a classifier from the default route table.
+// The returned classifier is safe for concurrent use.
+func NewOperationClassifier() *OperationClassifier {
+	c := &OperationClassifier{}
+
+	// Use a nil-safe null policy for all routes — we only need the
+	// operationID from the leaf, not a working policy.
+	p := NewNullPolicy()
+
+	routes := buildClassifierRoutes(p)
+	for _, r := range routes {
+		rm := r.(*RouteMux)
+		method, path, err := splitMuxPattern(rm.Pattern)
+		if err != nil {
+			continue
+		}
+		c.trie.add([]string{method}, path, rm.policy, rm.attrs, rm.poolName, rm.operationID)
+	}
+
+	return c
+}
+
+// Classify returns the [OperationID] for the given HTTP method and path.
+// Returns [OpOther] for unrecognized method+path combinations.
+func (c *OperationClassifier) Classify(method, path string) OperationID {
+	m, ok := c.trie.match(method, path)
+	if !ok {
+		return OpOther
+	}
+	return m.operationID
+}
+
+// buildClassifierRoutes constructs the route table with OperationID tags
+// but using a single shared null policy. This avoids creating real role-based
+// policies (which need live connections) for pure classification use.
+func buildClassifierRoutes(p Policy) []Route {
+	r := roleRoutes{
+		ingestWrite:    p,
+		ingestMgmt:     p,
+		searchRead:     p,
+		getRead:        p,
+		dataWrite:      p,
+		dataRefresh:    p,
+		dataFlush:      p,
+		dataForceMerge: p,
+		dataMgmt:       p,
+		searchMgmt:     p,
+		warmMgmt:       p,
+	}
+	return buildRoleRoutes(r)
+}

opensearchtransport/classify_test.go

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// The OpenSearch Contributors require contributions made to
+// this file be licensed under the Apache-2.0 license or a
+// compatible open source license.
+
+package opensearchtransport_test
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/opensearch-project/opensearch-go/v4/opensearchtransport"
+)
+
+func TestOperationClassifier(t *testing.T) {
+	t.Parallel()
+	c := opensearchtransport.NewOperationClassifier()
+
+	tests := []struct {
+		name   string
+		method string
+		path   string
+		want   opensearchtransport.OperationID
+	}{
+		// Bulk
+		{"bulk POST", http.MethodPost, "/_bulk", opensearchtransport.OpBulk},
+		{"bulk PUT", http.MethodPut, "/_bulk", opensearchtransport.OpBulk},
+		{"bulk with index", http.MethodPost, "/my-index/_bulk", opensearchtransport.OpBulk},
+		{"bulk stream", http.MethodPost, "/_bulk/stream", opensearchtransport.OpBulkStream},
+		{"reindex", http.MethodPost, "/_reindex", opensearchtransport.OpReindex},
+
+		// Search
+		{"search GET", http.MethodGet, "/_search", opensearchtransport.OpSearch},
+		{"search POST", http.MethodPost, "/_search", opensearchtransport.OpSearch},
+		{"search with index", http.MethodPost, "/events/_search", opensearchtransport.OpSearch},
+		{"msearch", http.MethodPost, "/_msearch", opensearchtransport.OpMSearch},
+		{"count", http.MethodGet, "/_count", opensearchtransport.OpCount},
+		{"count with index", http.MethodPost, "/events/_count", opensearchtransport.OpCount},
+		{"delete_by_query", http.MethodPost, "/events/_delete_by_query", opensearchtransport.OpDeleteByQuery},
+		{"update_by_query", http.MethodPost, "/events/_update_by_query", opensearchtransport.OpUpdateByQuery},
+		{"validate", http.MethodGet, "/_validate/query", opensearchtransport.OpValidate},
+		{"rank_eval", http.MethodPost, "/_rank_eval", opensearchtransport.OpRankEval},
+		{"search shards", http.MethodGet, "/_search_shards", opensearchtransport.OpSearchShards},
+		{"field caps", http.MethodGet, "/_field_caps", opensearchtransport.OpFieldCaps},
+
+		// Templates
+		{"search template", http.MethodPost, "/_search/template", opensearchtransport.OpSearchTemplate},
+		{"search template with index", http.MethodPost, "/events/_search/template", opensearchtransport.OpSearchTemplate},
+		{"msearch template", http.MethodPost, "/_msearch/template", opensearchtransport.OpMSearchTmpl},
+
+		// Scroll
+		{"scroll get", http.MethodGet, "/_search/scroll", opensearchtransport.OpScrollGet},
+		{"scroll post", http.MethodPost, "/_search/scroll", opensearchtransport.OpScrollGet},
+		{"scroll delete", http.MethodDelete, "/_search/scroll", opensearchtransport.OpScrollDelete},
+
+		// PIT
+		{"pit create", http.MethodPost, "/events/_search/point_in_time", opensearchtransport.OpPITCreate},
+		{"pit delete", http.MethodDelete, "/_search/point_in_time", opensearchtransport.OpPITDelete},
+		{"pit list", http.MethodGet, "/_search/point_in_time/_all", opensearchtransport.OpPITList},
+
+		// Document ops
+		{"doc get", http.MethodGet, "/events/_doc/123", opensearchtransport.OpDocGet},
+		{"doc exists", http.MethodHead, "/events/_doc/123", opensearchtransport.OpDocExists},
+		{"doc index PUT", http.MethodPut, "/events/_doc/123", opensearchtransport.OpDocIndex},
+		{"doc index POST", http.MethodPost, "/events/_doc", opensearchtransport.OpDocIndex},
+		{"doc create", http.MethodPut, "/events/_create/123", opensearchtransport.OpDocCreate},
+		{"doc update", http.MethodPost, "/events/_update/123", opensearchtransport.OpDocUpdate},
+		{"doc delete", http.MethodDelete, "/events/_doc/123", opensearchtransport.OpDocDelete},
+		{"source get", http.MethodGet, "/events/_source/123", opensearchtransport.OpDocSourceGet},
+		{"source exists", http.MethodHead, "/events/_source/123", opensearchtransport.OpDocSourceExist},
+		{"mget", http.MethodPost, "/_mget", opensearchtransport.OpMGet},
+		{"termvectors", http.MethodGet, "/events/_termvectors", opensearchtransport.OpTermVectors},
+		{"mtermvectors", http.MethodPost, "/_mtermvectors", opensearchtransport.OpMTermVectors},
+		{"explain", http.MethodPost, "/events/_explain/123", opensearchtransport.OpExplain},
+
+		// Ingest
+		{"ingest get", http.MethodGet, "/_ingest/pipeline/my-pipe", opensearchtransport.OpIngestGet},
+		{"ingest get all", http.MethodGet, "/_ingest/pipeline", opensearchtransport.OpIngestGet},
+		{"ingest create", http.MethodPut, "/_ingest/pipeline/my-pipe", opensearchtransport.OpIngestCreate},
+		{"ingest delete", http.MethodDelete, "/_ingest/pipeline/my-pipe", opensearchtransport.OpIngestDelete},
+		{"ingest simulate", http.MethodPost, "/_ingest/pipeline/my-pipe/_simulate", opensearchtransport.OpIngestSimulate},
+
+		// Maintenance
+		{"refresh", http.MethodPost, "/_refresh", opensearchtransport.OpRefresh},
+		{"refresh index", http.MethodPost, "/events/_refresh", opensearchtransport.OpRefresh},
+		{"flush", http.MethodPost, "/_flush", opensearchtransport.OpFlush},
+		{"flush synced", http.MethodPost, "/_flush/synced", opensearchtransport.OpFlush},
+		{"forcemerge", http.MethodPost, "/_forcemerge", opensearchtransport.OpForceMerge},
+		{"segments", http.MethodGet, "/_segments", opensearchtransport.OpSegments},
+		{"cache clear", http.MethodPost, "/_cache/clear", opensearchtransport.OpCacheClear},
+		{"recovery", http.MethodGet, "/events/_recovery", opensearchtransport.OpRecovery},
+		{"shard stores", http.MethodGet, "/events/_shard_stores", opensearchtransport.OpShardStores},
+		{"stats", http.MethodGet, "/_stats", opensearchtransport.OpStats},
+		{"stats with metric", http.MethodGet, "/_stats/indexing", opensearchtransport.OpStats},
+		{"stats with index", http.MethodGet, "/events/_stats", opensearchtransport.OpStats},
+
+		// Rethrottle
+		{"reindex rethrottle", http.MethodPost, "/_reindex/task1/_rethrottle", opensearchtransport.OpReindexRethrottle},
+		{"ubq rethrottle", http.MethodPost, "/_update_by_query/task1/_rethrottle", opensearchtransport.OpUBQRethrottle},
+		{"dbq rethrottle", http.MethodPost, "/_delete_by_query/task1/_rethrottle", opensearchtransport.OpDBQRethrottle},
+
+		// Cluster info
+		{"root GET", http.MethodGet, "/", opensearchtransport.OpClusterInfo},
+		{"root HEAD", http.MethodHead, "/", opensearchtransport.OpClusterInfo},
+
+		// Unknown
+		{"unrecognized path", http.MethodGet, "/_unknown/endpoint", opensearchtransport.OpOther},
+		{"unrecognized method", "DESTROY", "/_search", opensearchtransport.OpOther},
+		{"empty path", http.MethodGet, "", opensearchtransport.OpOther},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := c.Classify(tt.method, tt.path)
+			assert.Equal(t, tt.want, got, "Classify(%q, %q) = %s, want %s",
+				tt.method, tt.path, got, tt.want)
+		})
+	}
+}
+
+func TestOperationClassifier_ConcurrentSafety(t *testing.T) {
+	t.Parallel()
+	c := opensearchtransport.NewOperationClassifier()
+
+	const goroutines = 50
+	done := make(chan struct{})
+	for range goroutines {
+		go func() {
+			defer func() { done <- struct{}{} }()
+			for range 500 {
+				c.Classify(http.MethodPost, "/events/_search")
+				c.Classify(http.MethodPost, "/_bulk")
+				c.Classify(http.MethodGet, "/events/_doc/123")
+			}
+		}()
+	}
+	for range goroutines {
+		<-done
+	}
+}
+
+func TestOperationID_Masking(t *testing.T) {
+	t.Parallel()
+
+	t.Run("IsWrite", func(t *testing.T) {
+		t.Parallel()
+		assert.False(t, opensearchtransport.OpSearch.IsWrite())
+		assert.False(t, opensearchtransport.OpDocGet.IsWrite())
+		assert.True(t, opensearchtransport.OpBulk.IsWrite())
+		assert.True(t, opensearchtransport.OpDocIndex.IsWrite())
+		assert.True(t, opensearchtransport.OpDocDelete.IsWrite())
+	})
+
+	t.Run("IsRead", func(t *testing.T) {
+		t.Parallel()
+		assert.True(t, opensearchtransport.OpSearch.IsRead())
+		assert.True(t, opensearchtransport.OpDocGet.IsRead())
+		assert.False(t, opensearchtransport.OpBulk.IsRead())
+		assert.False(t, opensearchtransport.OpDocIndex.IsRead())
+	})
+
+	t.Run("Category", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, opensearchtransport.CatSearch, opensearchtransport.OpSearch.Category())
+		assert.Equal(t, opensearchtransport.CatSearch, opensearchtransport.OpMSearch.Category())
+		assert.Equal(t, opensearchtransport.CatSearch, opensearchtransport.OpCount.Category())
+		assert.Equal(t, opensearchtransport.CatBulk, opensearchtransport.OpBulk.Category())
+		assert.Equal(t, opensearchtransport.CatDocRead, opensearchtransport.OpDocGet.Category())
+		assert.Equal(t, opensearchtransport.CatDocWrite, opensearchtransport.OpDocIndex.Category())
+	})
+
+	t.Run("IsSearchFamily", func(t *testing.T) {
+		t.Parallel()
+		isSearchFamily := func(op opensearchtransport.OperationID) bool {
+			return op.Category() == opensearchtransport.CatSearch
+		}
+		assert.True(t, isSearchFamily(opensearchtransport.OpSearch))
+		assert.True(t, isSearchFamily(opensearchtransport.OpMSearch))
+		assert.True(t, isSearchFamily(opensearchtransport.OpCount))
+		assert.False(t, isSearchFamily(opensearchtransport.OpBulk))
+		assert.False(t, isSearchFamily(opensearchtransport.OpDocGet))
+	})
+}
+
+func TestOperationID_String(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		op   opensearchtransport.OperationID
+		want string
+	}{
+		{opensearchtransport.OpSearch, "search"},
+		{opensearchtransport.OpMSearch, "msearch"},
+		{opensearchtransport.OpCount, "count"},
+		{opensearchtransport.OpBulk, "bulk"},
+		{opensearchtransport.OpBulkStream, "bulk_stream"},
+		{opensearchtransport.OpReindex, "reindex"},
+		{opensearchtransport.OpDocGet, "doc_get"},
+		{opensearchtransport.OpDocIndex, "doc_index"},
+		{opensearchtransport.OpDocDelete, "doc_delete"},
+		{opensearchtransport.OpDocCreate, "doc_create"},
+		{opensearchtransport.OpDocUpdate, "doc_update"},
+		{opensearchtransport.OpScrollGet, "scroll_get"},
+		{opensearchtransport.OpScrollDelete, "scroll_delete"},
+		{opensearchtransport.OpRefresh, "refresh"},
+		{opensearchtransport.OpFlush, "flush"},
+		{opensearchtransport.OpForceMerge, "forcemerge"},
+		{opensearchtransport.OpStats, "stats"},
+		{opensearchtransport.OpClusterInfo, "cluster_info"},
+		{opensearchtransport.OpPing, "ping"},
+		{opensearchtransport.OpOther, "other"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.want, func(t *testing.T) {
+			t.Parallel()
+			require.Equal(t, tt.want, tt.op.String())
+		})
+	}
+}