metadata

Documentation

Index

• Constants
• func Authorization(ctx context.Context) string
• func Decode(ctx context.Context, encodedMetadata EncodedBytes) context.Context
• func NewTraceID() string
• func RequestHeader(ctx context.Context, name string) string
• func TraceID(ctx context.Context) string
• func Value(ctx context.Context, key string, out any) bool
• func WithAuthorization(ctx context.Context, auth string) context.Context
• func WithRequestHeaders(ctx context.Context, headers map[string][]string) context.Context
• func WithRoute(ctx context.Context, route EndpointRoute) context.Context
• func WithTraceID(ctx context.Context, id string) context.Context
• func WithValue(ctx context.Context, key string, value any) context.Context
• type EncodedBytes
  • func Encode(ctx context.Context) EncodedBytes
• type EndpointRoute
  • func Route(ctx context.Context) EndpointRoute
  • func (e EndpointRoute) QualifiedName() string

Constants

const Header = "X-RPC-Metadata"

Functions

func Authorization

func Authorization(ctx context.Context) string

Authorization extracts the original caller's metadata authorization credentials.

func Decode

func Decode(ctx context.Context, encodedMetadata EncodedBytes) context.Context

func NewTraceID

func NewTraceID() string

NewTraceID generates a pseudo-random request id for your context/request if one wasn't already provided by the client/caller.

func RequestHeader

func RequestHeader(ctx context.Context, name string) string

RequestHeader fetches a header from the original gateway request. What this corresponds to is completely dependent on the gateway that is serving up the request. For instance, if it is an HTTP/API gateway, this will read one of the original http.Request headers. If this is an event gateway request, this might not give you anything as we don't currently have a notion of event headers (yet?).

THESE VALUES DO NOT FOLLOW YOU if your request makes RPC-style calls or triggers other event gateways to fire. It only represents the most recent/current request context.

func TraceID

func TraceID(ctx context.Context) string

TraceID extracts the special metadata value that provides a consistent identifier used to trace requests as they go from service to service.

func Value

func Value(ctx context.Context, key string, out any) bool

Value looks up a single piece of metadata on the specified context. The 'key' is the name of the value you're looking for and 'out' is a pointer to the value you want us to fill in - the mechanics are similar to json.Unmarshal().

func WithAuthorization

func WithAuthorization(ctx context.Context, auth string) context.Context

WithAuthorization stores the user's/caller's auth credentials on the request context. Typically, you will not need to call this yourself as the framework will take care of this for you. You just need to call metadata.Authorization() when you need to check that value.

func WithRequestHeaders

func WithRequestHeaders(ctx context.Context, headers map[string][]string) context.Context

WithRequestHeaders stores header info from the original gateway request. This would be HTTP headers for API gateways, for example. You typically should not call this on your own as the framework will do that for you as part of our gateways' standard processing.

func WithRoute

func WithRoute(ctx context.Context, route EndpointRoute) context.Context

WithRoute stores the current operation/endpoint being invoked. Typically, you will not need to call this yourself as the framework will take care of this for you. You just need to call metadata.Endpoint() when you need to check that value.

func WithTraceID

func WithTraceID(ctx context.Context, id string) context.Context

WithTraceID stores this special tracing metadata value on the request context. Typically, you should NOT call this directly. The framework will infer/generate/propagate this value automatically.

func WithValue

func WithValue(ctx context.Context, key string, value any) context.Context

WithValue stores a key/value pair in the context metadata. It returns a new context that contains the metadata map with your value.

Types

type EncodedBytes

type EncodedBytes string

func Encode

func Encode(ctx context.Context) EncodedBytes

type EndpointRoute

type EndpointRoute struct {
	// ServiceName is the name of the service that this operation is part of.
	ServiceName string
	// Name is the name of the function/operation that this endpoint describes.
	Name string
	// Type indicates the type of gateway/route that triggered the operation to be
	// invoked in the first place. This is a way for you to check if the service is
	// being handled due to an API call or some sort of event handler.
	Type string
	// Method describes some sort of action/verb that describes this route. For API endpoints
	// it is the HTTP method (e.g. GET, PUT, POST, etc). For events, it is "ON", and so forth.
	Method string
	// Path describes the actual unique routing path that the gateway should use to ensure
	// that requests get to this endpoint. For API endpoints, it's the request path
	// like "/user/{ID}" and for event endpoints, it's the subscription key like "FooService.Save".
	Path string
	// Status passes along the route's HTTP ### value from doc options when applicable. This is
	// automatically set to 200 for event-based routes for a consistent "OK nothing went wrong" default.
	Status int
	// Roles are used for role-based security where you can say that this endpoint requires the user/caller
	// to have either "admin.write" or "group.write" privileges. When defining your services, you can parameterize
	// your roles such as "group.{ID}.write", but the ones stored in this slice should have already been
	// resolved with the appropriate runtime values (e.g. "group.123.write").
	//
	// Friendly reminder that these are the roles you want the security layer to look for - it's
	// not necessarily what the caller actually has!
	Roles []string
}

EndpointRoute stores a subset of the master endpoint information that you might want for logging and lookup. It does not include any of the actual functionality fields such as handlers/factories.

func Route

func Route(ctx context.Context) EndpointRoute

Route extracts the info about the current operation/endpoint being invoked.

func (EndpointRoute) QualifiedName

func (e EndpointRoute) QualifiedName() string

QualifiedName returns the fully-qualified name/identifier of this service operation. It is simply the formatted string "ServiceName.MethodName".