metainfo

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2024 License: Apache-2.0 Imports: 4 Imported by: 110

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 business 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-"
	HTTPPrefixBackward   = "rpc-backward-"
)

HTTP header prefixes.

View Source 
const (
	PrefixPersistent         = "RPC_PERSIST_"
	PrefixTransient          = "RPC_TRANSIT_"
	PrefixTransientUpstream  = "RPC_TRANSIT_UPSTREAM_"
	PrefixBackward           = "RPC_BACKWARD_"
	PrefixBackwardDownstream = "RPC_BACKWARD_DOWNSTREAM_"
)

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 CountPersistentValues 

func CountPersistentValues(ctx context.Context) int

CountPersistentValues counts the length of persisten KV pairs

func CountValues 

func CountValues(ctx context.Context) int

CountValues counts the length of transient KV pairs

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 

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 

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 GetBackwardValueToSend 

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

GetBackwardValueToSend gets a value associated with the given key that is set by `SendBackwardValue`, `SendBackwardValues` or `SendBackwardValuesFromMap`.

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 GetValueToMap 

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

GetValueToMap retrieves the value set into the context by the given key and set the value to the input map. Only use this function when you want to get a small set of values instead of GetAllValues. The logic of getting value follows GetAllValues, transient value has higher priority if key is same.

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 RangePersistentValues 

func RangePersistentValues(ctx context.Context, f func(k, v string) bool)

RangePersistentValues calls f sequentially for each persistent kv. If f returns false, range stops the iteration.

func RangeValues 

func RangeValues(ctx context.Context, f func(k, v string) bool)

RangeValues calls f sequentially for each transient kv. If f returns false, range stops the iteration.

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. Any key or value that does not follow the HTTP specification will be discarded.

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 into the context by the given key. This value will be propagated to the services along the RPC call chain.

func WithPersistentValues 

func WithPersistentValues(ctx context.Context, kvs ...string) context.Context

WithPersistentValues sets the values into the context by the given keys. 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.

func WithValues 

func WithValues(ctx context.Context, kvs ...string) context.Context

WithValue sets the values into the context by the given keys. 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 WithPersistentValues if you want to pass key/value pairs 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.