package coprocess

Get desktop application:
View/edit binary Protocol Buffers messages

Dispatcher is the service interface that must be implemented by the target language.

• rpc Dispatch (Object, Object)

  coprocess_object.proto:53

  Dispatch is an RPC method that accepts and returns an Object.

  message Object

  coprocess_object.proto:14

  Object wraps a MiniRequestObject and contains additional fields that are useful for users that implement their own request dispatchers, like the middleware hook type and name.

  • HookType hook_type = 1

    HookType is an enumeration that identifies the plugin hook type.

  • string hook_name = 2

    HookName is the plugin name.

  • optional MiniRequestObject request = 3

    Request relates to the main request data structure used by rich plugins. It’s used for middleware calls and contains important fields like headers, parameters, body and URL.

  • optional SessionState session = 4

    Session stores information about the current key/user that’s used for authentication.

  • map<string, string> metadata = 5

    Metadata is a dynamic filed that contains the metadata.

  • map<string, string> spec = 6

    Spec contains information about API definition, including APIID, OrgID and config_data.

  • optional ResponseObject response = 7

    Response relates to the ResponseObject used by response hooks. The fields are populated with the upstream HTTP response data. All the field contents can be modified.

• rpc DispatchEvent (Event, EventReply)

  coprocess_object.proto:56

  DispatchEvent dispatches an event to the target language.

  message Event

  coprocess_object.proto:41

  Event is represented as a JSON payload.

  • string payload = 1

    Payload represents the JSON payload.

  message EventReply

  coprocess_object.proto:48

  EventReply is the response for event.

  (message has no fields)

AccessDefinition is defined as an attribute within a SessionState instance. Contains the allowed versions and URLs (endpoints) for the API that the session request relates to. Each URL (endpoint) specifies an associated list of allowed methods. See also AccessSpec.

Used in: SessionState

• string api_name = 1

  ApiName is the name of the API that the session request relates to.

• string api_id = 2

  ApiId is the ID of the API that the session request relates to.

• repeated string versions = 3

  Versions is a list of allowed API versions, e.g. `"versions": [ "Default" ]`.

• repeated AccessSpec allowed_urls = 4

  AllowedUrls is a list of AccessSpec instances. Each instance defines a URL (endpoint) with an associated allowed list of methods. If all URLs (endpoints) are allowed then the attribute is not set.

AccessSpec defines an API's URL (endpoint) and associated list of allowed methods.

Used in: AccessDefinition

• string url = 1

  Url is a URL (endpoint) belonging to the API associated with the request session.

• repeated string methods = 2

  Methods is a list of allowed methods for the URL (endpoint), e.g. 'methods': [ 'GET'. 'POST', 'PUT', 'PATCH' ] The list of methods are case sensitive.

BasicAuthData contains a hashed password and the name of the hashing algorithm used.

Used in: SessionState

• string password = 1

  Password is a hashed password.

• string hash = 2

  Hash is the name of the hashing algorithm used to hash the password, e.g. bcrypt, Argon2.

Header is a reponse header that contains multiple associated values.

Used in: ResponseObject

• string key = 1

  Key represents the name of the header.

• repeated string values = 2

  Values is a list of values for a given header content.

HookType is an enumeration that identifies the type of plugin.

Used in: Object

• Unknown = 0

  Unknown is used for error checking and handling of an unrecognised hook type.

• Pre = 1

  Pre is executed before request sent to upstream target and before any authentication information is extracted from the header or parameter list of the request. Applies to both keyless and protected APIs.

• Post = 2

  Post is executed after authentication, validation, throttling and quota-limiting middleware has been executed, just before the request is proxied upstream. Use this to post-process a request before sending it to upstream API. This is only called when using protected APIs.

• PostKeyAuth = 3

  PostKeyAuth is executed after authentication, validation, throttling, and quota-limiting middleware has been executed, just before the request is proxied upstream. Use this to post-process a request before sending it to upstream API. This is only called when using protected APIs.

• CustomKeyCheck = 4

  CustomKeyCheck is executed for performing customised authentication.

• Response = 5

  Response is executed after the upstream API replies. The arguments passed to this hook include both the request and response data. Use this to modify the HTTP response before it’s sent to the client. This hook also receives the request object, the session object, the metadata and API definition associated with the request.

JWTData is added to sessions where a Tyk key (embedding a shared secret) is used as the public key for signing the JWT. This message contains the shared secret.

Used in: SessionState

• string secret = 1

  Secret is the shared secret.

MiniRequestObject is used for middleware calls and contains important fields like headers, parameters, body and URL.

Used in: Object

• map<string, string> headers = 1

  Headers is a read-only field for reading headers injected by previous middleware.

• map<string, string> set_headers = 2

  SetHeaders is a map of header key values to append to the request.

• repeated string delete_headers = 3

  DeleteHeaders is a list of header names to be removed from the request.

• string body = 4

  Body is the request body.

• string url = 5

  Url is the request URL.

• map<string, string> params = 6

  Params is a read only map of request params.

• map<string, string> add_params = 7

  AddParams is a map of parameter keys and values to add to the request.

• map<string, string> extended_params = 8

  ExtendedParams allows a parameter to have multiple values, currently unsupported.

• repeated string delete_params = 9

  DeleteParams is a list of parameter keys to be removed from the request.

• optional ReturnOverrides return_overrides = 10

  ReturnOverrides override the response for the request, see ReturnOverrides.

• string method = 11

  Method is the request method, eg GET, POST, etc.

• string request_uri = 12

  RequestUri is the raw unprocessed request URL, including query string and fragments.

• string scheme = 13

  Scheme is the URL scheme, e.g. http or https.

• bytes raw_body = 14

  RawBody is the raw request body.

Monitor allows API endpoint users, stakeholders or an organisation to be notified by webhook when certain quota limits have been reached for their session token.

Used in: SessionState

• repeated double trigger_limits = 1

  TriggerLimits is a list of quota percentage limits, defined in descending order.

ResponseObject is used by response hooks. All fields are modifiable.

Used in: Object

• int32 status_code = 1

  StatusCode is the HTTP status code received from the upstream.

• bytes raw_body = 2

  RawBody represents the raw bytes of HTTP response body.

• string body = 3

  Body represents the HTTP response body. Excluded when the raw_body contains invalid UTF-8 characters.

• map<string, string> headers = 4

  Headers represents the headers received from upstream.

• repeated Header multivalue_headers = 5

  MultivalueHeaders is a list of headers. Useful when header has multiple values. See Header.

ReturnOverrides is used to override the response for a given HTTP request When returned within an Object for a given HTTP request, the upstream reponse is replaced with the fields encapsulated within ReturnOverrides.

Used in: MiniRequestObject

• int32 response_code = 1

  ResponseCode overrides the upstream response status code.

• string response_error = 2

  ResponseError overrides the upstream response error message.

• map<string, string> headers = 3

  Headers overrides the upstream response headers.

• bool override_error = 4

  OverrideError overrides the upstream error response with response_error when set to true.

• string response_body = 5

  ResponseBody is an alias of response_error that contains the response body.

SessionState is created for every authenticated request and stored in Redis. Used to track the activity of a given key in different ways, mainly by the built-in Tyk middleware such as the quota middleware or the rate limiter. A GRPC plugin is able to create a SessionState object and store it in the same way built-in authentication mechanisms do.

Used in: Object

• int64 last_check = 1

  LastCheck is deprecated.

• double allowance = 2

  Allowance is deprecated, replaced by rate.

• double rate = 3

  Rate is the number of requests that are allowed in the specified rate limiting window.

• double per = 4

  Per is the duration of the rate window, in seconds.

• int64 expires = 5

  Expires is an epoch that defines when the key should expire.

• int64 quota_max = 6

  QuotaMax is the maximum number of requests allowed during the quota period.

• int64 quota_renews = 7

  QuotaRenews is an epoch that defines when the quota renews.

• int64 quota_remaining = 8

  QuotaRemaining is the number of requests remaining for this user’s quota (unrelated to rate limit).

• int64 quota_renewal_rate = 9

  QuotaRenewalRate is the time in seconds during which the quota is valid. So for 1000 requests per hour, this value would be 3600 while quota_max and quota_remaining would be 1000.

• map<string, AccessDefinition> access_rights = 10

  AccessRights maps the session's API ID to an AccessDefinition. The AccessDefinition defines the access rights for the API in terms of allowed: versions and URLs(endpoints). Each URL (endpoint) has a list of allowed methods.

• string org_id = 11

  OrgId represents the organisation the session user belongs to. This can be used in conjunction with the org_id setting in the API Definition object to have tokens owned by organisations.

• string oauth_client_id = 12

  OauthClientId is the OAuth client ID that is set if the token is generated by an OAuth client during an OAuth authorisation flow.

• map<string, string> oauth_keys = 13

  OauthKeys maps an OAuth client ID with a corresponding access token value. Currently unsupported and under development.

• optional BasicAuthData basic_auth_data = 14

  BasicAuthData contains a hashed password and the name of the hashing algorithm used.

• optional JWTData jwt_data = 15

  JwtData is added to sessions where a Tyk key (embedding a shared secret) is used as the public key for signing the JWT. The JWT token's KID header value references the ID of a Tyk key.

• bool hmac_enabled = 16

  HmacEnabled is set to `true` to indicate generation of a HMAC signature using the secret provided in `hmac_secret`. If the generated signature matches the signature provided in the Authorizaton header then authentication of the request has passed.

• string hmac_secret = 17

  HmacSecret represents the HMAC secret.

• bool is_inactive = 18

  IsInactive when set to true, indicates that access is denied.

• string apply_policy_id = 19

  ApplyPolicyId represents the policy ID that is bound to the token. Deprecated use apply_policies instead.

• int64 data_expires = 20

  DataExpires is a value, in seconds, that defines when data generated by the session token expires in the analytics DB (must be using Pro edition and MongoDB).

• optional Monitor monitor = 21

  Monitor represents the quota monitor settings, currently unsupported in gRPC sessions.

• bool enable_detailed_recording = 22

  EnableDetailedRecording should be set to true to have Tyk store the inbound request and outbound response data in HTTP Wire format as part of the analytics data.

• map<string, string> metadata = 23

  Metadata represents meta-data to be included as part of the session that can be used in other middleware such as transforms and header injection to embed user-specific data into a request, or alternatively to query the providence of a key.

• repeated string tags = 24

  Tags is a list of tags to embed into analytics data when the request completes. If a policy has tags, those tags take precedence and are used instead.

• string alias = 25

  Alias is an identifier for the token for use in analytics, to allow easier tracing of hashed and unhashed tokens.

• string last_updated = 26

  LastUpdated is a timestamp that represents the time the session was last updated. With *PostAuth* hooks this is a UNIX timestamp.

• int64 id_extractor_deadline = 27

  IdExtractorDeadline is a UNIX timestamp that signifies when a cached key or ID will expire. This relates to custom authentication, where authenticated keys can be cached to save repeated requests to the gRPC server.

• int64 session_lifetime = 28

  SessionLifetime is a UNIX timestamp that denotes when the key will automatically expire. Any·subsequent API request made using the key will be rejected. Overrides the global session lifetime.

• repeated string apply_policies = 29

  ApplyPolicies is a list of IDs for the policies that are bound to the token.

• string certificate = 30

  Certificate is the client certificate used to authenticate the request. Exists in the session instance if mTLS is configured for the API. Currently unsupported.

• int64 max_query_depth = 31

  MaxQueryDepth relates to graphQL APIs. If the session key has a maximum query depth limit defined then it is included in the session instance. Currently unsupported and under development.

StringSlice is a list of strings.

• repeated string items = 1

  Items is a list of string items.