metainfo

package
Version: v0.0.0-...-e4efae9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 10, 2021 License: Apache-2.0 Imports: 3 Imported by: 7

README

metainfo

This library provides a set of methods to store and manipulate meta information in golang's context.Context for inter-service data transmission.

Meta information is designed as key-value pairs of strings and keys are case-sensitive.

Meta information is divided into two kinds: transient and persistent -- the former is passed from a client to a server and disappears from the network while the latter should be passed to the other servers (if the current server plays a client role, too) and go on until some server discards it.

Because we uses golang's context.Context to carry meta information, we need to distinguish the transient information comes from a client and those set by the current service since they will be stored in the same context object. So we introduce a third kind of meta information transient-upstream to denote the transient information received from a client. The transient-upstream kind is designed to achieve the semantic of transient meta information and is indistinguishable from the transient kind with the APIs from a user perspective.

This library is designed as a set of methods operating on context.Context. The way data is transmitted between services should be defined and implemented by frameworks that support this library. Usually, end users should not be concerned about this but rely on the APIs only.

Framework Support Guide

To introduce metainfo into a certain framework, to following conditions should be satisfied:

  1. Protocol used by the framework for data transmission should support meta information (HTTP headers, header transport of the apache thrift framework, and so on).
  2. When the framework receives meta information as a server role, it needs to add those information to the context.Context (by using APIs in this library). Then, before going into the codes of end user (or other codes that requires meta information), the framework should use metainfo.TransferForward to convert transient information from the client into transient-upstream information.
  3. When the framework establishes a request towards a server as a client role, before sending out the meta information, it should call metainfo.TransferForward to discard transient-upstream information in the context.Context to make them "alive only one hop".

API Reference

Notice

  1. Meta information is designed as key-value pairs as strings.
  2. Empty string is invalid when used as a key or value.
  3. Due to the characteristics of context.Context, any modification on a context object is only visible to the codes that holds the context or its sub contexts.

Constants

Package metainfo provides serveral string prefixes to denote the kinds of meta information where context is not available (such as when transmiting data through network).

Typical codes for bussiness logic should never use prefixes. And frameworks that support metainfo may choose other approaches to achieve the same goal.

  • PrefixPersistent
  • PrefixTransient
  • PrefixTransientUpstream

Documentation

Index

Constants

View Source
const (
	HTTPPrefixTransient  = "rpc-transit-"
	HTTPPrefixPersistent = "rpc-persist-"
)

HTTP header prefixes.

View Source
const (
	PrefixPersistent        = "RPC_PERSIST_"
	PrefixTransient         = "RPC_TRANSIT_"
	PrefixTransientUpstream = "RPC_TRANSIT_UPSTREAM_"
)

The prefix listed below may be used to tag the types of values when there is no context to carry them.

Variables

This section is empty.

Functions

func AllBackwardValuesToSend

func AllBackwardValuesToSend(ctx context.Context) (m map[string]string)

AllBackwardValuesToSend retrieves all key-values pairs set by `SendBackwardValue` or `SendBackwardValues` from the given context. This function is designed for frameworks, common developers should not use it.

func CGIVariableToHTTPHeader

func CGIVariableToHTTPHeader(key string) string

CGIVariableToHTTPHeader converts a CGI variable into an HTTP header key. For example, `ABC_DEF` will be converted to `abc-def`.

func DelPersistentValue

func DelPersistentValue(ctx context.Context, k string) context.Context

DelPersistentValue deletes a persistent key/value from the current context. Since empty string value is not valid, we could just set the value to be empty.

func DelValue

func DelValue(ctx context.Context, k string) context.Context

DelValue deletes a key/value from the current context. Since empty string value is not valid, we could just set the value to be empty.

func FromHTTPHeader

func FromHTTPHeader(ctx context.Context, h HTTPHeaderCarrier) context.Context

FromHTTPHeader reads metainfo from a given HTTP header and sets them into the context. Note that this function does not call TransferForward inside.

func GetAllBackwardValues deprecated

This function has been deprecated.
func GetAllBackwardValues(ctx context.Context) map[string]string

GetAllBackwardValues is an alias to RecvAllBackwardValues. Deprecated: for clarity, please use `RecvAllBackwardValues` instead.

func GetAllPersistentValues

func GetAllPersistentValues(ctx context.Context) (m map[string]string)

GetAllPersistentValues retrieves all persistent values.

func GetAllValues

func GetAllValues(ctx context.Context) (m map[string]string)

GetAllValues retrieves all transient values

func GetBackwardValue deprecated

This function has been deprecated.
func GetBackwardValue(ctx context.Context, key string) (val string, ok bool)

GetBackwardValue is an alias to `RecvBackwardValue`. Deprecated: for clarity, please use `RecvBackwardValue` instead.

func GetPersistentValue

func GetPersistentValue(ctx context.Context, k string) (v string, ok bool)

GetPersistentValue retrieves the persistent value set into the context by the given key.

func GetValue

func GetValue(ctx context.Context, k string) (v string, ok bool)

GetValue retrieves the value set into the context by the given key.

func HTTPHeaderToCGIVariable

func HTTPHeaderToCGIVariable(key string) string

HTTPHeaderToCGIVariable performs an CGI variable conversion. For example, an HTTP header key `abc-def` will result in `ABC_DEF`.

func HasMetaInfo

func HasMetaInfo(ctx context.Context) bool

HasMetaInfo detects whether the given context contains metainfo.

func RecvAllBackwardValues

func RecvAllBackwardValues(ctx context.Context) (m map[string]string)

RecvAllBackwardValues is the batched version of RecvBackwardValue.

func RecvBackwardValue

func RecvBackwardValue(ctx context.Context, key string) (val string, ok bool)

RecvBackwardValue gets a value associated with the given key that is set by `SetBackwardValue` or `SetBackwardValues`.

func SaveMetaInfoToMap

func SaveMetaInfoToMap(ctx context.Context, m map[string]string)

SaveMetaInfoToMap set key-value pairs from ctx to m while filtering out transient-upstream data.

func SendBackwardValue

func SendBackwardValue(ctx context.Context, key, val string) (ok bool)

SendBackwardValue sets a key-value pair into the context for sending to a remote endpoint. Note that the values can not be retrieved with `RecvBackwardValue` from the same context.

func SendBackwardValues

func SendBackwardValues(ctx context.Context, kvs ...string) (ok bool)

SendBackwardValues is the batched version of `SendBackwardValue`.

func SendBackwardValuesFromMap

func SendBackwardValuesFromMap(ctx context.Context, kvs map[string]string) (ok bool)

SendBackwardValuesFromMap is the batched version of `SendBackwardValue`.

func SetBackwardValue

func SetBackwardValue(ctx context.Context, key, val string) (ok bool)

SetBackwardValue sets a key value pair into the context.

func SetBackwardValues

func SetBackwardValues(ctx context.Context, kvs ...string) (ok bool)

SetBackwardValues is the batched version of `SetBackwardValue`.

func SetBackwardValuesFromMap

func SetBackwardValuesFromMap(ctx context.Context, kvs map[string]string) (ok bool)

SetBackwardValuesFromMap is the batched version of `SetBackwardValue`.

func SetMetaInfoFromMap

func SetMetaInfoFromMap(ctx context.Context, m map[string]string) context.Context

SetMetaInfoFromMap retrieves metainfo key-value pairs from the given map and sets then into the context. Only those keys with prefixes defined in this module would be used. If the context has been carrying metanifo pairs, they will be merged as a basis.

func ToHTTPHeader

func ToHTTPHeader(ctx context.Context, h HTTPHeaderSetter)

ToHTTPHeader writes all metainfo into the given HTTP header. Note that this function does not call TransferForward inside.

func TransferForward

func TransferForward(ctx context.Context) context.Context

TransferForward converts transient values to transient-upstream values and filters out original transient-upstream values. It should be used before the context is passing from server to client.

func WithBackwardValues

func WithBackwardValues(ctx context.Context) context.Context

WithBackwardValues returns a new context that allows passing key-value pairs backward with `SetBackwardValue` from any derived context.

func WithBackwardValuesToSend

func WithBackwardValuesToSend(ctx context.Context) context.Context

WithBackwardValuesToSend returns a new context that collects key-value pairs set with `SendBackwardValue` or `SendBackwardValues` into any derived context.

func WithPersistentValue

func WithPersistentValue(ctx context.Context, k, v string) context.Context

WithPersistentValue sets the value info the context by the given key. This value will be propagated to the services along the RPC call chain.

func WithValue

func WithValue(ctx context.Context, k, v string) context.Context

WithValue sets the value into the context by the given key. This value will be propagated to the next service/endpoint through an RPC call.

Notice that it will not propagate any further beyond the next service/endpoint, Use WithPersistentValue if you want to pass a key/value pair all the way.

Types

type HTTPHeader

type HTTPHeader map[string][]string

HTTPHeader is provided to wrap an http.Header into an HTTPHeaderCarrier.

func (HTTPHeader) Set

func (h HTTPHeader) Set(key, value string)

Set sets the header entries associated with key to the single element value. The key will converted into lowercase as the HTTP/2 protocol requires.

func (HTTPHeader) Visit

func (h HTTPHeader) Visit(v func(k, v string))

Visit implements the HTTPHeaderCarrier interface.

type HTTPHeaderCarrier

type HTTPHeaderCarrier interface {
	Visit(func(k, v string))
}

HTTPHeaderCarrier accepts a visitor to access all key value pairs in an HTTP header.

type HTTPHeaderSetter

type HTTPHeaderSetter interface {
	Set(key, value string)
}

HTTPHeaderSetter sets a key with a value into a HTTP header.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL