contrib/valkey-io/valkey-go: Add WrapClient to support wrapping an existing client

[naoto0822]

Package Name

contrib/valkey-io/valkey-go

Package Version(s)

2.6.0

Describe the feature you'd like

I'd like a WrapClient function to be added that wraps an existing valkey.Client with tracing, similar to how other contrib packages work:

func WrapClient(valkeyClient valkey.Client, opts ...Option) (valkey.Client, error)

NewClient could then be refactored to call WrapClient internally, keeping full backward compatibility:

func NewClient(clientOption valkey.ClientOption, opts ...Option) (valkey.Client, error) {
	cli, err := valkey.NewClient(clientOption)
	if err != nil {
		return nil, err
	}
	return WrapClient(cli, opts...), nil
}

Is your feature request related to a problem?

When combining valkeyhook.WithHook with valkeytrace.NewClient, the wrapping order is constrained because NewClient creates the raw client internally. This forces the following structure:

// valkeytrace is inner, hook is outer — no choice
tracedCli, _ := valkeytrace.NewClient(clientOption, opts...)
cli := valkeyhook.WithHook(tracedCli, &myHook{})

With this order, the ctx received by the hook's Do method does not contain the valkeytrace span. Although valkeytrace calls tracer.StartSpanFromContext and stores the new span in an updated context, that updated context is never propagated back to the hook.

As a result, calling tracer.SpanFromContext(ctx) inside the hook returns the parent span (e.g. the HTTP handler span) instead of the valkeytrace span, causing tags to be set on the wrong span:

  HTTP span  ← SetTag ends up here (unintended)
    └─ valkey.command span (created by valkeytrace)

With WrapClient, it becomes possible to place the hook inside valkeytrace, so the hook's Do is called with a ctx that already contains the valkeytrace span:

rawCli, _  := valkey.NewClient(clientOption)
hookedCli  := valkeyhook.WithHook(rawCli, &myHook{})   // hook is inner
cli := valkeytrace.WrapClient(hookedCli, opts...) // valkeytrace is outer

  valkey.command span (valkeytrace)
    └─ hook's Do is called with ctx containing the valkeytrace span
         └─ tracer.SpanFromContext(ctx) = valkeytrace span ✓

Describe alternatives you've considered

1. Create a custom span inside the hook

Creating a new span via tracer.StartSpanFromContext inside the hook and attaching tags to it. However, this makes the custom span the parent of the valkeytrace span rather than being associated with it, which results in an unintended trace structure:

  HTTP span
    └─ custom span (created by hook) ← becomes parent of valkeytrace span
         └─ valkey.command span (valkeytrace)

2. Re-implement valkeytrace internally

Since valkeytrace.client is unexported, it is possible to write a local WrapClient equivalent that duplicates the tracing logic. This works, but introduces maintenance overhead and risks diverging from upstream behavior.

Additional context

Several other contrib/ packages already follow the WrapClient pattern to support use cases like middleware and hook composition (e.g. contrib/go-redis/redis.v8). Adding the same to the valkey package would bring it in line with the rest of the contrib ecosystem.

[darccio]

@rarguelloF I think it makes sense, right?