Add polymorphic Status field to task response structs

Add Status field (json.RawMessage) to TasksGetResp, TasksListTask, and
TaskCancelInfo for polymorphic task status data. Add typed status structs
matching the OpenSearch API specification: BulkByScrollTaskStatus,
ReplicationTaskStatus, ResyncTaskStatus, PersistentTaskStatus. Add
Parse* helpers and BulkByScrollTaskStatusOrException for sliced task
status.

Ref: opensearch-project#803
Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

CHANGELOG.md

@@ -12,6 +12,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Add per-attempt `RequestTimeout` to bound individual HTTP round-trips, preventing indefinite hangs on stalled connections ([#786](https://github.com/opensearch-project/opensearch-go/issues/786))
 - Add `opensearchutil/shardhash` package with exported `Hash` and `ForRouting` functions for computing OpenSearch shard routing
 - Enhanced cluster readiness checking for improved test reliability: `testutil.NewClient()` now includes readiness validation (health + cluster state + nodes info)
+- Add `Status` field (`json.RawMessage`) to `TasksGetResp`, `TasksListTask`, and `TaskCancelInfo` for polymorphic task status data; add typed status structs matching the OpenSearch API specification: `BulkByScrollTaskStatus`, `ReplicationTaskStatus`, `ResyncTaskStatus`, `PersistentTaskStatus`; add `Parse*` helpers and `BulkByScrollTaskStatusOrException` for sliced task status ([#788](https://github.com/opensearch-project/opensearch-go/issues/788))
 - 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
 - opensearchtransport/testutil package with PollUntil helper for eventual consistency testing (ISM policies, index readiness, cluster state changes)

_samples/tasks.go

@@ -0,0 +1,143 @@
+// 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 main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/opensearch-project/opensearch-go/v4"
+	"github.com/opensearch-project/opensearch-go/v4/opensearchapi"
+)
+
+func main() {
+	if err := example(); err != nil {
+		fmt.Println(fmt.Sprintf("Error: %s", err))
+		os.Exit(1)
+	}
+}
+
+func example() error {
+	// Initialize the client with SSL/TLS enabled.
+	client, err := opensearchapi.NewClient(
+		opensearchapi.Config{
+			Client: opensearch.Config{
+				InsecureSkipVerify: true, // For testing only. Use certificate for validation.
+				Addresses:          []string{"https://localhost:9200"},
+				Username:           "admin", // For testing only. Don't store credentials in code.
+				Password:           "myStrongPassword123!",
+			},
+		},
+	)
+	if err != nil {
+		return err
+	}
+
+	ctx := context.Background()
+
+	sourceIndex := "task-source"
+	destIndex := "task-dest"
+
+	// Create source index with test data.
+	_, err = client.Indices.Create(ctx, opensearchapi.IndicesCreateReq{
+		Index: sourceIndex,
+		Body:  strings.NewReader(`{"settings": {"number_of_shards": 1, "number_of_replicas": 0}}`),
+	})
+	if err != nil {
+		return err
+	}
+
+	_, err = client.Index(ctx, opensearchapi.IndexReq{
+		Index: sourceIndex,
+		Body:  strings.NewReader(`{"title": "Test Document", "year": 2024}`),
+		Params: opensearchapi.IndexParams{
+			Refresh: "true",
+		},
+	})
+	if err != nil {
+		return err
+	}
+
+	// Submit an async reindex task.
+	reindexResp, err := client.Reindex(ctx, opensearchapi.ReindexReq{
+		Body: strings.NewReader(fmt.Sprintf(
+			`{"source":{"index":"%s"},"dest":{"index":"%s"}}`,
+			sourceIndex, destIndex,
+		)),
+		Params: opensearchapi.ReindexParams{
+			WaitForCompletion: opensearchapi.ToPointer(false),
+		},
+	})
+	if err != nil {
+		return err
+	}
+	taskID := reindexResp.Task
+	fmt.Printf("Task submitted: %s\n", taskID)
+
+	// Poll for completion.
+	var taskResp *opensearchapi.TasksGetResp
+	for {
+		taskResp, err = client.Tasks.Get(ctx, opensearchapi.TasksGetReq{TaskID: taskID})
+		if err != nil {
+			return err
+		}
+		if taskResp.Completed {
+			break
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+	fmt.Printf("Task completed: action=%s\n", taskResp.Task.Action)
+
+	// Parse the BulkByScroll status.
+	status, err := opensearchapi.ParseBulkByScrollTaskStatus(taskResp.Task.Status)
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Total: %d\n", status.Total)
+	fmt.Printf("Created: %d\n", status.Created)
+	fmt.Printf("Updated: %d\n", status.Updated)
+	fmt.Printf("Deleted: %d\n", status.Deleted)
+	fmt.Printf("Batches: %d\n", status.Batches)
+	fmt.Printf("Version conflicts: %d\n", status.VersionConflicts)
+	fmt.Printf("Noops: %d\n", status.Noops)
+	fmt.Printf("Retries (bulk): %d\n", status.Retries.Bulk)
+	fmt.Printf("Retries (search): %d\n", status.Retries.Search)
+
+	// For tasks without a dedicated type, unmarshal as generic JSON.
+	if taskResp.Task.Status != nil {
+		var raw map[string]any
+		if err := json.Unmarshal(taskResp.Task.Status, &raw); err != nil {
+			return err
+		}
+		fmt.Printf("Raw status: %v\n", raw)
+	}
+
+	// List all running tasks.
+	listResp, err := client.Tasks.List(ctx, nil)
+	if err != nil {
+		return err
+	}
+	for nodeID, node := range listResp.Nodes {
+		fmt.Printf("Node %s (%s): %d tasks\n", node.Name, nodeID, len(node.Tasks))
+	}
+
+	// Cleanup.
+	delResp, err := client.Indices.Delete(ctx, opensearchapi.IndicesDeleteReq{
+		Indices: []string{sourceIndex, destIndex},
+		Params:  opensearchapi.IndicesDeleteParams{IgnoreUnavailable: opensearchapi.ToPointer(true)},
+	})
+	if err != nil {
+		return err
+	}
+	fmt.Printf("Deleted: %t\n", delResp.Acknowledged)
+
+	return nil
+}