Add methods to create a handler context and extract links from context

[bergundy]

Follow up to #42, this is so we can use AddHandlerLinks in the Temporal SDK.

[cretz]

I think these should be copied on return (new slice/array + https://pkg.go.dev/builtin#copy is quite cheap especially for small uses) and there should be a set links too

[bergundy]

Why? Are you worried about users mutating? Is it typical for Go libraries to protect users this way?

[cretz]

Yes and yes, e.g. https://github.com/grpc/grpc-go/blob/v1.70.0/metadata/metadata.go#L197. This is a very common approach for returning mutable collections that are rarely asked for (e.g. only once at the end in most cases). Also note the mutex isn't protecting the slice only the field (so if someone does AddHandlerLinks later you could get a race with a reader here).

[cretz]

Suggested change

	hctx := ctx.Value(handlerCtxKey).(*handlerCtx)
	hctx, ok := ctx.Value(handlerCtxKey).(*handlerCtx)
	if !ok {
	return nil
	}

Or if panic is intentional, document that it can panic if called outside of context (and possibly provide a way to know whether you're in a handler context). Same comment applies to AddHandlerLinks.

[bergundy]

I can document, the panic is intentional.

[cretz]

We should consider a utility to let a user know a context is a handler context then. Basically general utility users should be able to know whether something they are about to call will panic (and therefore can prevent it with a conditional)

[bergundy]

Sure, that makes sense.

[cretz]

Suggested change

	hctx.mu.Unlock()
	cpy := make([]Link, len(links))
	copy(cpy, links)
	cpy := make([]Link, len(links))
	copy(cpy, links)
	hctx.mu.Unlock()

The lock needs to be held while it is accessed

[bergundy]

Why? We always assign to h.links, we never mutate it directly.

[cretz]

It's a common misunderstanding in Go that append doesn't mutate the first param

[bergundy]

Thanks, I wasn't aware.