tyk icon indicating copy to clipboard operation
tyk copied to clipboard

[DX-1084] Add documentation to protobuf source code files for review

Open dcs3spp opened this issue 10 months ago • 9 comments

DX-1084

Description

  • Added documentation for protobuf messages and service for review
  • Task file has been updated to use a Python virtual environment.
  • The PR includes the bindings regenerated
  • The PR is large and has 22 files that includes the comments in the regenerated bindings. If required I can include just the protobuf files and then once reviewed include a separate PR for the bindings?

Related Issue

Motivation and Context

How This Has Been Tested

Screenshots (if appropriate)

Types of changes

  • [x] Bug fix (non-breaking change which fixes an issue)
  • [ ] New feature (non-breaking change which adds functionality)
  • [ ] Breaking change (fix or feature that would cause existing functionality to change)
  • [x] Refactoring or add test (improvements in base code or adds test coverage to functionality)

Checklist

  • [x] I ensured that the documentation is up to date
  • [ ] I explained why this PR updates go.mod in detail with reasoning why it's required
  • [ ] I would like a code coverage CI quality gate exception and have explained why

dcs3spp avatar Apr 25 '24 15:04 dcs3spp

API Changes

--- prev.txt	2024-06-25 15:54:16.129030630 +0000
+++ current.txt	2024-06-25 15:54:12.725040010 +0000
@@ -6300,12 +6300,23 @@
 TYPES
 
 type AccessDefinition struct {
-	ApiName     string        `protobuf:"bytes,1,opt,name=api_name,json=apiName,proto3" json:"api_name,omitempty"`
-	ApiId       string        `protobuf:"bytes,2,opt,name=api_id,json=apiId,proto3" json:"api_id,omitempty"`
-	Versions    []string      `protobuf:"bytes,3,rep,name=versions,proto3" json:"versions,omitempty"`
+
+	// ApiName is the name of the API that the session request relates to.
+	ApiName string `protobuf:"bytes,1,opt,name=api_name,json=apiName,proto3" json:"api_name,omitempty"`
+	// ApiId is the ID of the API that the session request relates to.
+	ApiId string `protobuf:"bytes,2,opt,name=api_id,json=apiId,proto3" json:"api_id,omitempty"`
+	// Versions is a list of allowed API versions, e.g.  `"versions": [ "Default" ]`.
+	Versions []string `protobuf:"bytes,3,rep,name=versions,proto3" json:"versions,omitempty"`
+	// 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.
 	AllowedUrls []*AccessSpec `protobuf:"bytes,4,rep,name=allowed_urls,json=allowedUrls,proto3" json:"allowed_urls,omitempty"`
 	// Has unexported 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.
 
 func (*AccessDefinition) Descriptor() ([]byte, []int)
     Deprecated: Use AccessDefinition.ProtoReflect.Descriptor instead.
@@ -6327,10 +6338,16 @@
 func (x *AccessDefinition) String() string
 
 type AccessSpec struct {
-	Url     string   `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"`
+
+	// Url is a URL (endpoint) belonging to the API associated with the request session.
+	Url string `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"`
+	// 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.
 	Methods []string `protobuf:"bytes,2,rep,name=methods,proto3" json:"methods,omitempty"`
 	// Has unexported fields.
 }
+    AccessSpec defines an API's URL (endpoint) and associated list of allowed
+    methods.
 
 func (*AccessSpec) Descriptor() ([]byte, []int)
     Deprecated: Use AccessSpec.ProtoReflect.Descriptor instead.
@@ -6348,10 +6365,15 @@
 func (x *AccessSpec) String() string
 
 type BasicAuthData struct {
+
+	// Password is a hashed password.
 	Password string `protobuf:"bytes,1,opt,name=password,proto3" json:"password,omitempty"`
-	Hash     string `protobuf:"bytes,2,opt,name=hash,proto3" json:"hash,omitempty"`
+	// Hash is the name of the hashing algorithm used to hash the password, e.g. bcrypt, Argon2.
+	Hash string `protobuf:"bytes,2,opt,name=hash,proto3" json:"hash,omitempty"`
 	// Has unexported fields.
 }
+    BasicAuthData contains a hashed password and the name of the hashing
+    algorithm used.
 
 func (*BasicAuthData) Descriptor() ([]byte, []int)
     Deprecated: Use BasicAuthData.ProtoReflect.Descriptor instead.
@@ -6391,7 +6413,9 @@
     PythonDispatcher for reference.
 
 type DispatcherClient interface {
+	// Dispatch is an RPC method that accepts and returns an Object.
 	Dispatch(ctx context.Context, in *Object, opts ...grpc.CallOption) (*Object, error)
+	// DispatchEvent dispatches an event to the target language.
 	DispatchEvent(ctx context.Context, in *Event, opts ...grpc.CallOption) (*EventReply, error)
 }
     DispatcherClient is the client API for Dispatcher service.
@@ -6402,17 +6426,22 @@
 func NewDispatcherClient(cc grpc.ClientConnInterface) DispatcherClient
 
 type DispatcherServer interface {
+	// Dispatch is an RPC method that accepts and returns an Object.
 	Dispatch(context.Context, *Object) (*Object, error)
+	// DispatchEvent dispatches an event to the target language.
 	DispatchEvent(context.Context, *Event) (*EventReply, error)
 }
     DispatcherServer is the server API for Dispatcher service. All
     implementations should embed UnimplementedDispatcherServer for forward
-    compatibility
+    compatibility.
 
 type Event struct {
+
+	// Payload represents the JSON payload.
 	Payload string `protobuf:"bytes,1,opt,name=payload,proto3" json:"payload,omitempty"`
 	// Has unexported fields.
 }
+    Event is represented as a JSON payload.
 
 func (*Event) Descriptor() ([]byte, []int)
     Deprecated: Use Event.ProtoReflect.Descriptor instead.
@@ -6430,6 +6459,7 @@
 type EventReply struct {
 	// Has unexported fields.
 }
+    EventReply is the response for event.
 
 func (*EventReply) Descriptor() ([]byte, []int)
     Deprecated: Use EventReply.ProtoReflect.Descriptor instead.
@@ -6443,10 +6473,14 @@
 func (x *EventReply) String() string
 
 type Header struct {
-	Key    string   `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
+
+	// Key represents the name of the header.
+	Key string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
+	// Values is a list of values for a given header content.
 	Values []string `protobuf:"bytes,2,rep,name=values,proto3" json:"values,omitempty"`
 	// Has unexported fields.
 }
+    Header is a reponse header that contains multiple associated values.
 
 func (*Header) Descriptor() ([]byte, []int)
     Deprecated: Use Header.ProtoReflect.Descriptor instead.
@@ -6464,14 +6498,33 @@
 func (x *Header) String() string
 
 type HookType int32
+    HookType is an enumeration that identifies the type of plugin.
 
 const (
-	HookType_Unknown        HookType = 0
-	HookType_Pre            HookType = 1
-	HookType_Post           HookType = 2
-	HookType_PostKeyAuth    HookType = 3
+	// Unknown is used for error checking and handling of an unrecognised hook type.
+	HookType_Unknown HookType = 0
+	// 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.
+	HookType_Pre HookType = 1
+	// 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.
+	HookType_Post HookType = 2
+	// 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.
+	HookType_PostKeyAuth HookType = 3
+	// CustomKeyCheck is executed for performing customised authentication.
 	HookType_CustomKeyCheck HookType = 4
-	HookType_Response       HookType = 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.
+	HookType_Response HookType = 5
 )
 func (HookType) Descriptor() protoreflect.EnumDescriptor
 
@@ -6487,9 +6540,14 @@
 func (HookType) Type() protoreflect.EnumType
 
 type JWTData struct {
+
+	// Secret is the shared secret.
 	Secret string `protobuf:"bytes,1,opt,name=secret,proto3" json:"secret,omitempty"`
 	// Has unexported fields.
 }
+    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.
 
 func (*JWTData) Descriptor() ([]byte, []int)
     Deprecated: Use JWTData.ProtoReflect.Descriptor instead.
@@ -6505,22 +6563,39 @@
 func (x *JWTData) String() string
 
 type MiniRequestObject struct {
-	Headers         map[string]string `protobuf:"bytes,1,rep,name=headers,proto3" json:"headers,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	SetHeaders      map[string]string `protobuf:"bytes,2,rep,name=set_headers,json=setHeaders,proto3" json:"set_headers,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	DeleteHeaders   []string          `protobuf:"bytes,3,rep,name=delete_headers,json=deleteHeaders,proto3" json:"delete_headers,omitempty"`
-	Body            string            `protobuf:"bytes,4,opt,name=body,proto3" json:"body,omitempty"`
-	Url             string            `protobuf:"bytes,5,opt,name=url,proto3" json:"url,omitempty"`
-	Params          map[string]string `protobuf:"bytes,6,rep,name=params,proto3" json:"params,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	AddParams       map[string]string `protobuf:"bytes,7,rep,name=add_params,json=addParams,proto3" json:"add_params,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	ExtendedParams  map[string]string `protobuf:"bytes,8,rep,name=extended_params,json=extendedParams,proto3" json:"extended_params,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	DeleteParams    []string          `protobuf:"bytes,9,rep,name=delete_params,json=deleteParams,proto3" json:"delete_params,omitempty"`
-	ReturnOverrides *ReturnOverrides  `protobuf:"bytes,10,opt,name=return_overrides,json=returnOverrides,proto3" json:"return_overrides,omitempty"`
-	Method          string            `protobuf:"bytes,11,opt,name=method,proto3" json:"method,omitempty"`
-	RequestUri      string            `protobuf:"bytes,12,opt,name=request_uri,json=requestUri,proto3" json:"request_uri,omitempty"`
-	Scheme          string            `protobuf:"bytes,13,opt,name=scheme,proto3" json:"scheme,omitempty"`
-	RawBody         []byte            `protobuf:"bytes,14,opt,name=raw_body,json=rawBody,proto3" json:"raw_body,omitempty"`
+
+	// Headers is a read-only field for reading headers injected by previous middleware.
+	Headers map[string]string `protobuf:"bytes,1,rep,name=headers,proto3" json:"headers,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// SetHeaders is a map of header key values to append to the request.
+	SetHeaders map[string]string `protobuf:"bytes,2,rep,name=set_headers,json=setHeaders,proto3" json:"set_headers,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// DeleteHeaders is a list of header names to be removed from the request.
+	DeleteHeaders []string `protobuf:"bytes,3,rep,name=delete_headers,json=deleteHeaders,proto3" json:"delete_headers,omitempty"`
+	// Body is the request body.
+	Body string `protobuf:"bytes,4,opt,name=body,proto3" json:"body,omitempty"`
+	// Url is the request URL.
+	Url string `protobuf:"bytes,5,opt,name=url,proto3" json:"url,omitempty"`
+	// Params is a read only map of request params.
+	Params map[string]string `protobuf:"bytes,6,rep,name=params,proto3" json:"params,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// AddParams is a map of parameter keys and values to add to the request.
+	AddParams map[string]string `protobuf:"bytes,7,rep,name=add_params,json=addParams,proto3" json:"add_params,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// ExtendedParams allows a parameter to have multiple values, currently unsupported.
+	ExtendedParams map[string]string `protobuf:"bytes,8,rep,name=extended_params,json=extendedParams,proto3" json:"extended_params,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// DeleteParams is a list of parameter keys to be removed from the request.
+	DeleteParams []string `protobuf:"bytes,9,rep,name=delete_params,json=deleteParams,proto3" json:"delete_params,omitempty"`
+	// ReturnOverrides override the response for the request, see ReturnOverrides.
+	ReturnOverrides *ReturnOverrides `protobuf:"bytes,10,opt,name=return_overrides,json=returnOverrides,proto3" json:"return_overrides,omitempty"`
+	// Method is the request method, eg GET, POST, etc.
+	Method string `protobuf:"bytes,11,opt,name=method,proto3" json:"method,omitempty"`
+	// RequestUri is the raw unprocessed request URL, including query string and fragments.
+	RequestUri string `protobuf:"bytes,12,opt,name=request_uri,json=requestUri,proto3" json:"request_uri,omitempty"`
+	// Scheme is the URL scheme, e.g. http or https.
+	Scheme string `protobuf:"bytes,13,opt,name=scheme,proto3" json:"scheme,omitempty"`
+	// RawBody is the raw request body.
+	RawBody []byte `protobuf:"bytes,14,opt,name=raw_body,json=rawBody,proto3" json:"raw_body,omitempty"`
 	// Has unexported fields.
 }
+    MiniRequestObject is used for middleware calls and contains important fields
+    like headers, parameters, body and URL.
 
 func (*MiniRequestObject) Descriptor() ([]byte, []int)
     Deprecated: Use MiniRequestObject.ProtoReflect.Descriptor instead.
@@ -6562,9 +6637,14 @@
 func (x *MiniRequestObject) String() string
 
 type Monitor struct {
+
+	// TriggerLimits is a list of quota percentage limits, defined in descending order.
 	TriggerLimits []float64 `protobuf:"fixed64,1,rep,packed,name=trigger_limits,json=triggerLimits,proto3" json:"trigger_limits,omitempty"`
 	// Has unexported fields.
 }
+    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.
 
 func (*Monitor) Descriptor() ([]byte, []int)
     Deprecated: Use Monitor.ProtoReflect.Descriptor instead.
@@ -6580,15 +6660,28 @@
 func (x *Monitor) String() string
 
 type Object struct {
-	HookType HookType           `protobuf:"varint,1,opt,name=hook_type,json=hookType,proto3,enum=coprocess.HookType" json:"hook_type,omitempty"`
-	HookName string             `protobuf:"bytes,2,opt,name=hook_name,json=hookName,proto3" json:"hook_name,omitempty"`
-	Request  *MiniRequestObject `protobuf:"bytes,3,opt,name=request,proto3" json:"request,omitempty"`
-	Session  *SessionState      `protobuf:"bytes,4,opt,name=session,proto3" json:"session,omitempty"`
-	Metadata map[string]string  `protobuf:"bytes,5,rep,name=metadata,proto3" json:"metadata,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	Spec     map[string]string  `protobuf:"bytes,6,rep,name=spec,proto3" json:"spec,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	Response *ResponseObject    `protobuf:"bytes,7,opt,name=response,proto3" json:"response,omitempty"`
-	// Has unexported fields.
-}
+
+	// HookType is an enumeration that identifies the plugin hook type.
+	HookType HookType `protobuf:"varint,1,opt,name=hook_type,json=hookType,proto3,enum=coprocess.HookType" json:"hook_type,omitempty"`
+	// HookName is the plugin name.
+	HookName string `protobuf:"bytes,2,opt,name=hook_name,json=hookName,proto3" json:"hook_name,omitempty"`
+	// 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.
+	Request *MiniRequestObject `protobuf:"bytes,3,opt,name=request,proto3" json:"request,omitempty"`
+	// Session stores information about the current key/user that’s used for authentication.
+	Session *SessionState `protobuf:"bytes,4,opt,name=session,proto3" json:"session,omitempty"`
+	// Metadata is a dynamic filed that contains the metadata.
+	Metadata map[string]string `protobuf:"bytes,5,rep,name=metadata,proto3" json:"metadata,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// Spec contains information about API definition, including APIID, OrgID and config_data.
+	Spec map[string]string `protobuf:"bytes,6,rep,name=spec,proto3" json:"spec,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// 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.
+	Response *ResponseObject `protobuf:"bytes,7,opt,name=response,proto3" json:"response,omitempty"`
+	// Has unexported fields.
+}
+    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.
 
 func (*Object) Descriptor() ([]byte, []int)
     Deprecated: Use Object.ProtoReflect.Descriptor instead.
@@ -6616,13 +6709,20 @@
 func (x *Object) String() string
 
 type ResponseObject struct {
-	StatusCode        int32             `protobuf:"varint,1,opt,name=status_code,json=statusCode,proto3" json:"status_code,omitempty"`
-	RawBody           []byte            `protobuf:"bytes,2,opt,name=raw_body,json=rawBody,proto3" json:"raw_body,omitempty"`
-	Body              string            `protobuf:"bytes,3,opt,name=body,proto3" json:"body,omitempty"`
-	Headers           map[string]string `protobuf:"bytes,4,rep,name=headers,proto3" json:"headers,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	MultivalueHeaders []*Header         `protobuf:"bytes,5,rep,name=multivalue_headers,json=multivalueHeaders,proto3" json:"multivalue_headers,omitempty"`
+
+	// StatusCode is the HTTP status code received from the upstream.
+	StatusCode int32 `protobuf:"varint,1,opt,name=status_code,json=statusCode,proto3" json:"status_code,omitempty"`
+	// RawBody represents the raw bytes of HTTP response body.
+	RawBody []byte `protobuf:"bytes,2,opt,name=raw_body,json=rawBody,proto3" json:"raw_body,omitempty"`
+	// Body represents the HTTP response body. Excluded when the raw_body contains invalid UTF-8 characters.
+	Body string `protobuf:"bytes,3,opt,name=body,proto3" json:"body,omitempty"`
+	// Headers represents the headers received from upstream.
+	Headers map[string]string `protobuf:"bytes,4,rep,name=headers,proto3" json:"headers,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// MultivalueHeaders is a list of headers. Useful when header has multiple values. See Header.
+	MultivalueHeaders []*Header `protobuf:"bytes,5,rep,name=multivalue_headers,json=multivalueHeaders,proto3" json:"multivalue_headers,omitempty"`
 	// Has unexported fields.
 }
+    ResponseObject is used by response hooks. All fields are modifiable.
 
 func (*ResponseObject) Descriptor() ([]byte, []int)
     Deprecated: Use ResponseObject.ProtoReflect.Descriptor instead.
@@ -6646,13 +6746,22 @@
 func (x *ResponseObject) String() string
 
 type ReturnOverrides struct {
-	ResponseCode  int32             `protobuf:"varint,1,opt,name=response_code,json=responseCode,proto3" json:"response_code,omitempty"`
-	ResponseError string            `protobuf:"bytes,2,opt,name=response_error,json=responseError,proto3" json:"response_error,omitempty"`
-	Headers       map[string]string `protobuf:"bytes,3,rep,name=headers,proto3" json:"headers,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	OverrideError bool              `protobuf:"varint,4,opt,name=override_error,json=overrideError,proto3" json:"override_error,omitempty"`
-	ResponseBody  string            `protobuf:"bytes,5,opt,name=response_body,json=responseBody,proto3" json:"response_body,omitempty"`
+
+	// ResponseCode overrides the upstream response status code.
+	ResponseCode int32 `protobuf:"varint,1,opt,name=response_code,json=responseCode,proto3" json:"response_code,omitempty"`
+	// ResponseError overrides the upstream response error message.
+	ResponseError string `protobuf:"bytes,2,opt,name=response_error,json=responseError,proto3" json:"response_error,omitempty"`
+	// Headers overrides the upstream response headers.
+	Headers map[string]string `protobuf:"bytes,3,rep,name=headers,proto3" json:"headers,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// OverrideError overrides the upstream error response with response_error when set to true.
+	OverrideError bool `protobuf:"varint,4,opt,name=override_error,json=overrideError,proto3" json:"override_error,omitempty"`
+	// ResponseBody is an alias of response_error that contains the response body.
+	ResponseBody string `protobuf:"bytes,5,opt,name=response_body,json=responseBody,proto3" json:"response_body,omitempty"`
 	// Has unexported fields.
 }
+    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.
 
 func (*ReturnOverrides) Descriptor() ([]byte, []int)
     Deprecated: Use ReturnOverrides.ProtoReflect.Descriptor instead.
@@ -6676,39 +6785,98 @@
 func (x *ReturnOverrides) String() string
 
 type SessionState struct {
-	LastCheck               int64                        `protobuf:"varint,1,opt,name=last_check,json=lastCheck,proto3" json:"last_check,omitempty"`
-	Allowance               float64                      `protobuf:"fixed64,2,opt,name=allowance,proto3" json:"allowance,omitempty"`
-	Rate                    float64                      `protobuf:"fixed64,3,opt,name=rate,proto3" json:"rate,omitempty"`
-	Per                     float64                      `protobuf:"fixed64,4,opt,name=per,proto3" json:"per,omitempty"`
-	Expires                 int64                        `protobuf:"varint,5,opt,name=expires,proto3" json:"expires,omitempty"`
-	QuotaMax                int64                        `protobuf:"varint,6,opt,name=quota_max,json=quotaMax,proto3" json:"quota_max,omitempty"`
-	QuotaRenews             int64                        `protobuf:"varint,7,opt,name=quota_renews,json=quotaRenews,proto3" json:"quota_renews,omitempty"`
-	QuotaRemaining          int64                        `protobuf:"varint,8,opt,name=quota_remaining,json=quotaRemaining,proto3" json:"quota_remaining,omitempty"`
-	QuotaRenewalRate        int64                        `protobuf:"varint,9,opt,name=quota_renewal_rate,json=quotaRenewalRate,proto3" json:"quota_renewal_rate,omitempty"`
-	AccessRights            map[string]*AccessDefinition `protobuf:"bytes,10,rep,name=access_rights,json=accessRights,proto3" json:"access_rights,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	OrgId                   string                       `protobuf:"bytes,11,opt,name=org_id,json=orgId,proto3" json:"org_id,omitempty"`
-	OauthClientId           string                       `protobuf:"bytes,12,opt,name=oauth_client_id,json=oauthClientId,proto3" json:"oauth_client_id,omitempty"`
-	OauthKeys               map[string]string            `protobuf:"bytes,13,rep,name=oauth_keys,json=oauthKeys,proto3" json:"oauth_keys,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	BasicAuthData           *BasicAuthData               `protobuf:"bytes,14,opt,name=basic_auth_data,json=basicAuthData,proto3" json:"basic_auth_data,omitempty"`
-	JwtData                 *JWTData                     `protobuf:"bytes,15,opt,name=jwt_data,json=jwtData,proto3" json:"jwt_data,omitempty"`
-	HmacEnabled             bool                         `protobuf:"varint,16,opt,name=hmac_enabled,json=hmacEnabled,proto3" json:"hmac_enabled,omitempty"`
-	HmacSecret              string                       `protobuf:"bytes,17,opt,name=hmac_secret,json=hmacSecret,proto3" json:"hmac_secret,omitempty"`
-	IsInactive              bool                         `protobuf:"varint,18,opt,name=is_inactive,json=isInactive,proto3" json:"is_inactive,omitempty"`
-	ApplyPolicyId           string                       `protobuf:"bytes,19,opt,name=apply_policy_id,json=applyPolicyId,proto3" json:"apply_policy_id,omitempty"`
-	DataExpires             int64                        `protobuf:"varint,20,opt,name=data_expires,json=dataExpires,proto3" json:"data_expires,omitempty"`
-	Monitor                 *Monitor                     `protobuf:"bytes,21,opt,name=monitor,proto3" json:"monitor,omitempty"`
-	EnableDetailedRecording bool                         `protobuf:"varint,22,opt,name=enable_detailed_recording,json=enableDetailedRecording,proto3" json:"enable_detailed_recording,omitempty"`
-	Metadata                map[string]string            `protobuf:"bytes,23,rep,name=metadata,proto3" json:"metadata,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	Tags                    []string                     `protobuf:"bytes,24,rep,name=tags,proto3" json:"tags,omitempty"`
-	Alias                   string                       `protobuf:"bytes,25,opt,name=alias,proto3" json:"alias,omitempty"`
-	LastUpdated             string                       `protobuf:"bytes,26,opt,name=last_updated,json=lastUpdated,proto3" json:"last_updated,omitempty"`
-	IdExtractorDeadline     int64                        `protobuf:"varint,27,opt,name=id_extractor_deadline,json=idExtractorDeadline,proto3" json:"id_extractor_deadline,omitempty"`
-	SessionLifetime         int64                        `protobuf:"varint,28,opt,name=session_lifetime,json=sessionLifetime,proto3" json:"session_lifetime,omitempty"`
-	ApplyPolicies           []string                     `protobuf:"bytes,29,rep,name=apply_policies,json=applyPolicies,proto3" json:"apply_policies,omitempty"`
-	Certificate             string                       `protobuf:"bytes,30,opt,name=certificate,proto3" json:"certificate,omitempty"`
-	MaxQueryDepth           int64                        `protobuf:"varint,31,opt,name=max_query_depth,json=maxQueryDepth,proto3" json:"max_query_depth,omitempty"`
-	// Has unexported fields.
-}
+
+	// LastCheck is deprecated.
+	LastCheck int64 `protobuf:"varint,1,opt,name=last_check,json=lastCheck,proto3" json:"last_check,omitempty"`
+	// Allowance is deprecated, replaced by rate.
+	Allowance float64 `protobuf:"fixed64,2,opt,name=allowance,proto3" json:"allowance,omitempty"`
+	// Rate is the number of requests that are allowed in the specified rate limiting window.
+	Rate float64 `protobuf:"fixed64,3,opt,name=rate,proto3" json:"rate,omitempty"`
+	// Per is the duration of the rate window, in seconds.
+	Per float64 `protobuf:"fixed64,4,opt,name=per,proto3" json:"per,omitempty"`
+	// Expires is an epoch that defines when the key should expire.
+	Expires int64 `protobuf:"varint,5,opt,name=expires,proto3" json:"expires,omitempty"`
+	// QuotaMax is the maximum number of requests allowed during the quota period.
+	QuotaMax int64 `protobuf:"varint,6,opt,name=quota_max,json=quotaMax,proto3" json:"quota_max,omitempty"`
+	// QuotaRenews is an epoch that defines when the quota renews.
+	QuotaRenews int64 `protobuf:"varint,7,opt,name=quota_renews,json=quotaRenews,proto3" json:"quota_renews,omitempty"`
+	// QuotaRemaining is the number of requests remaining for this user’s quota (unrelated to rate
+	// limit).
+	QuotaRemaining int64 `protobuf:"varint,8,opt,name=quota_remaining,json=quotaRemaining,proto3" json:"quota_remaining,omitempty"`
+	// 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.
+	QuotaRenewalRate int64 `protobuf:"varint,9,opt,name=quota_renewal_rate,json=quotaRenewalRate,proto3" json:"quota_renewal_rate,omitempty"`
+	// 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.
+	AccessRights map[string]*AccessDefinition `protobuf:"bytes,10,rep,name=access_rights,json=accessRights,proto3" json:"access_rights,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// 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.
+	OrgId string `protobuf:"bytes,11,opt,name=org_id,json=orgId,proto3" json:"org_id,omitempty"`
+	// OauthClientId is the OAuth client ID that is set if the token is generated by an OAuth client during an
+	// OAuth authorisation flow.
+	OauthClientId string `protobuf:"bytes,12,opt,name=oauth_client_id,json=oauthClientId,proto3" json:"oauth_client_id,omitempty"`
+	// OauthKeys maps an OAuth client ID with a corresponding access token value. Currently unsupported and under development.
+	OauthKeys map[string]string `protobuf:"bytes,13,rep,name=oauth_keys,json=oauthKeys,proto3" json:"oauth_keys,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// BasicAuthData contains a hashed password and the name of the hashing algorithm used.
+	BasicAuthData *BasicAuthData `protobuf:"bytes,14,opt,name=basic_auth_data,json=basicAuthData,proto3" json:"basic_auth_data,omitempty"`
+	// 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.
+	JwtData *JWTData `protobuf:"bytes,15,opt,name=jwt_data,json=jwtData,proto3" json:"jwt_data,omitempty"`
+	// 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.
+	HmacEnabled bool `protobuf:"varint,16,opt,name=hmac_enabled,json=hmacEnabled,proto3" json:"hmac_enabled,omitempty"`
+	// HmacSecret represents the HMAC secret.
+	HmacSecret string `protobuf:"bytes,17,opt,name=hmac_secret,json=hmacSecret,proto3" json:"hmac_secret,omitempty"`
+	// IsInactive when set to true, indicates that access is denied.
+	IsInactive bool `protobuf:"varint,18,opt,name=is_inactive,json=isInactive,proto3" json:"is_inactive,omitempty"`
+	// ApplyPolicyId represents the policy ID that is bound to the token. Deprecated use apply_policies instead.
+	ApplyPolicyId string `protobuf:"bytes,19,opt,name=apply_policy_id,json=applyPolicyId,proto3" json:"apply_policy_id,omitempty"`
+	// 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).
+	DataExpires int64 `protobuf:"varint,20,opt,name=data_expires,json=dataExpires,proto3" json:"data_expires,omitempty"`
+	// Monitor represents the quota monitor settings, currently unsupported in gRPC sessions.
+	Monitor *Monitor `protobuf:"bytes,21,opt,name=monitor,proto3" json:"monitor,omitempty"`
+	// 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.
+	EnableDetailedRecording bool `protobuf:"varint,22,opt,name=enable_detailed_recording,json=enableDetailedRecording,proto3" json:"enable_detailed_recording,omitempty"`
+	// 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.
+	Metadata map[string]string `protobuf:"bytes,23,rep,name=metadata,proto3" json:"metadata,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// 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.
+	Tags []string `protobuf:"bytes,24,rep,name=tags,proto3" json:"tags,omitempty"`
+	// Alias is an identifier for the token for use in analytics, to allow easier tracing of hashed
+	// and unhashed tokens.
+	Alias string `protobuf:"bytes,25,opt,name=alias,proto3" json:"alias,omitempty"`
+	// LastUpdated is a timestamp that represents the time the session was last updated.
+	// With *PostAuth* hooks this is a UNIX timestamp.
+	LastUpdated string `protobuf:"bytes,26,opt,name=last_updated,json=lastUpdated,proto3" json:"last_updated,omitempty"`
+	// 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.
+	IdExtractorDeadline int64 `protobuf:"varint,27,opt,name=id_extractor_deadline,json=idExtractorDeadline,proto3" json:"id_extractor_deadline,omitempty"`
+	// 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.
+	SessionLifetime int64 `protobuf:"varint,28,opt,name=session_lifetime,json=sessionLifetime,proto3" json:"session_lifetime,omitempty"`
+	// ApplyPolicies is a list of IDs for the policies that are bound to the token.
+	ApplyPolicies []string `protobuf:"bytes,29,rep,name=apply_policies,json=applyPolicies,proto3" json:"apply_policies,omitempty"`
+	// Certificate is the client certificate used to authenticate the request. Exists in the session instance if mTLS is configured
+	// for the API. Currently unsupported.
+	Certificate string `protobuf:"bytes,30,opt,name=certificate,proto3" json:"certificate,omitempty"`
+	// 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.
+	MaxQueryDepth int64 `protobuf:"varint,31,opt,name=max_query_depth,json=maxQueryDepth,proto3" json:"max_query_depth,omitempty"`
+	// Has unexported fields.
+}
+    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.
 
 func (*SessionState) Descriptor() ([]byte, []int)
     Deprecated: Use SessionState.ProtoReflect.Descriptor instead.
@@ -6784,9 +6952,12 @@
 func (x *SessionState) String() string
 
 type StringSlice struct {
+
+	// Items is a list of string items.
 	Items []string `protobuf:"bytes,1,rep,name=items,proto3" json:"items,omitempty"`
 	// Has unexported fields.
 }
+    StringSlice is a list of strings.
 
 func (*StringSlice) Descriptor() ([]byte, []int)
     Deprecated: Use StringSlice.ProtoReflect.Descriptor instead.

github-actions[bot] avatar Apr 25 '24 15:04 github-actions[bot]

PR Description updated to latest commit (https://github.com/TykTechnologies/tyk/commit/2bd312e290f39de803faaa69cc407705f1b9696a)

github-actions[bot] avatar Apr 25 '24 15:04 github-actions[bot]

:boom: CI tests failed :see_no_evil:

git-state

diff --git a/coprocess/coprocess_common.pb.go b/coprocess/coprocess_common.pb.go
index bdc0686..ccd0561 100644
--- a/coprocess/coprocess_common.pb.go
+++ b/coprocess/coprocess_common.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_mini_request_object.pb.go b/coprocess/coprocess_mini_request_object.pb.go
index 07136e3..184464b 100644
--- a/coprocess/coprocess_mini_request_object.pb.go
+++ b/coprocess/coprocess_mini_request_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_object.pb.go b/coprocess/coprocess_object.pb.go
index b3b4cd1..6fab2b8 100644
--- a/coprocess/coprocess_object.pb.go
+++ b/coprocess/coprocess_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_object_grpc.pb.go b/coprocess/coprocess_object_grpc.pb.go
index 8b48ff7..8423d03 100644
--- a/coprocess/coprocess_object_grpc.pb.go
+++ b/coprocess/coprocess_object_grpc.pb.go
@@ -8,6 +8,7 @@ package coprocess
 
 import (
 	context "context"
+
 	grpc "google.golang.org/grpc"
 	codes "google.golang.org/grpc/codes"
 	status "google.golang.org/grpc/status"
diff --git a/coprocess/coprocess_response_object.pb.go b/coprocess/coprocess_response_object.pb.go
index 87283f3..3970c8b 100644
--- a/coprocess/coprocess_response_object.pb.go
+++ b/coprocess/coprocess_response_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_return_overrides.pb.go b/coprocess/coprocess_return_overrides.pb.go
index ddee20b..f3e8454 100644
--- a/coprocess/coprocess_return_overrides.pb.go
+++ b/coprocess/coprocess_return_overrides.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_session_state.pb.go b/coprocess/coprocess_session_state.pb.go
index b542cc3..b1cbd61 100644
--- a/coprocess/coprocess_session_state.pb.go
+++ b/coprocess/coprocess_session_state.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (

Please look at the run or in the Checks tab.

github-actions[bot] avatar Apr 25 '24 15:04 github-actions[bot]

PR Review

⏱️ Estimated effort to review [1-5]

3, because the PR involves multiple files with significant changes, including updates to protobuf definitions and generated code. Understanding the implications of these changes requires a good grasp of the project's architecture and the protobuf system.

🧪 Relevant tests

No

🔍 Possible issues

Possible Bug: The removal of the reflect and sync imports in the Go files might lead to runtime errors if these packages are used elsewhere in the code without explicit imports.

Compatibility Issue: The upgrade of protobuf versions in the Go files might introduce compatibility issues with other parts of the system that depend on the older protobuf version.

🔒 Security concerns

No

Code feedback:
relevant filecoprocess/coprocess_session_state.pb.go
suggestion      

Consider verifying backward compatibility of the protobuf changes. Upgrading protobuf versions can introduce changes that are not backward compatible. Ensure that these changes do not break existing implementations that depend on the older version. [important]

relevant line// protoc-gen-go v1.32.0

relevant filecoprocess/coprocess_session_state.pb.go
suggestion      

Ensure that the removed imports (reflect and sync) are not used elsewhere in the code without being re-imported. This change could potentially lead to runtime errors if these packages are referenced without being explicitly imported in the files. [important]

relevant line- reflect "reflect"

relevant filecoprocess/coprocess_session_state.pb.go
suggestion      

Add unit tests for the new fields added to the protobuf definitions to ensure they are serialized and deserialized correctly. This is crucial for maintaining data integrity and system stability. [important]

relevant line// The shared secret

relevant filecoprocess/coprocess_session_state.pb.go
suggestion      

Review the newly added comments for clarity and completeness. Some comments are quite brief and do not fully explain the purpose or usage of the associated fields. Expanding these comments would improve code readability and maintainability. [medium]

relevant line// The shared secret


✨ Review tool usage guide:

Overview: The review tool scans the PR code changes, and generates a PR review which includes several types of feedbacks, such as possible PR issues, security threats and relevant test in the PR. More feedbacks can be added by configuring the tool.

The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on any PR.

  • When commenting, to edit configurations related to the review tool (pr_reviewer section), use the following template:
/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...
[pr_reviewer]
some_config1=...
some_config2=...

See the review usage page for a comprehensive guide on using this tool.

github-actions[bot] avatar Apr 25 '24 15:04 github-actions[bot]

PR Code Suggestions

CategorySuggestions                                                                                                                                                       
Possible issue
Remove duplicate hook type descriptions to avoid confusion and maintain clarity in the codebase.

Remove the duplicate description for HookType_Post and HookType_PostKeyAuth as they are
identical and might be a copy-paste error. Consider revising the description if they are
meant to be different, or remove one if they are indeed the same.

coprocess/coprocess_common.pb.go [36-43]

 // 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.
 HookType_Post HookType = 2
-// 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.
-HookType_PostKeyAuth HookType = 3
 
Add error handling for the AddSerializedFile method call.

Ensure that the AddSerializedFile method call is properly checked for errors or
exceptions. This is important because failing to load a serialized file correctly can lead
to runtime errors. Consider wrapping this call in a try-except block to handle potential
exceptions.

coprocess/bindings/python/coprocess_common_pb2.py [17]

-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x16\x63oprocess_common.proto\x12\tcoprocess\"\x1c\n\x0bStringSlice\x12\r\n\x05items\x18\x01 \x03(\t*]\n\x08HookType\x12\x0b\n\x07Unknown\x10\x00\x12\x07\n\x03Pre\x10\x01\x12\x08\n\x04Post\x10\x02\x12\x0f\n\x0bPostKeyAuth\x10\x03\x12\x12\n\x0e\x43ustomKeyCheck\x10\x04\x12\x0c\n\x08Response\x10\x05\x42\x0cZ\n/coprocessb\x06proto3')
+try:
+    DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x16\x63oprocess_common.proto\x12\tcoprocess\"\x1c\n\x0bStringSlice\x12\r\n\x05items\x18\x01 \x03(\t*]\n\x08HookType\x12\x0b\n\x07Unknown\x10\x00\x12\x07\n\x03Pre\x10\x01\x12\x08\n\x04Post\x10\x02\x12\x0f\n\x0bPostKeyAuth\x10\x03\x12\x12\n\x0e\x43ustomKeyCheck\x10\x04\x12\x0c\n\x08Response\x10\x05\x42\x0cZ\n/coprocessb\x06proto3')
+except Exception as e:
+    # Handle exception, possibly logging the error or re-raising with additional context
+    raise RuntimeError("Failed to add serialized file to descriptor pool.") from e
 
Best practice
Rename Url to URL to adhere to Go's naming conventions for abbreviations.

Consider renaming Url to URL to follow Go's convention of capitalizing abbreviations.

coprocess/coprocess_mini_request_object.pb.go [37]

 // Request URL
-Url string `protobuf:"bytes,5,opt,name=url,proto3" json:"url,omitempty"`
+URL string `protobuf:"bytes,5,opt,name=url,proto3" json:"url,omitempty"`
 
Enhancement
Add a check for valid UTF-8 in RawBody before assigning to Body to prevent potential runtime errors.

Consider adding error handling or a check to ensure that RawBody contains valid UTF-8
before assigning it to Body. This can prevent runtime errors due to invalid UTF-8
sequences.

coprocess/coprocess_response_object.pb.go [33]

-// HTTP response body. Excluded when the raw_body contains invalid UTF-8 characters
-Body string `protobuf:"bytes,3,opt,name=body,proto3" json:"body,omitempty"`
+if utf8.Valid(rawBody) {
+    // HTTP response body. Excluded when the raw_body contains invalid UTF-8 characters
+    Body string `protobuf:"bytes,3,opt,name=body,proto3" json:"body,omitempty"`
+}
 
Improve the clarity of the comment for the ReturnOverrides struct.

Consider using a more descriptive comment for the ReturnOverrides struct to explain its
usage more clearly.

coprocess/coprocess_return_overrides.pb.go [23-26]

-// Used to override the response for a given HTTP request
+// ReturnOverrides modifies the HTTP response for a specific request.
 //
-// When returned within an Object for a given HTTP request, the upstream reponse
-// is replaced with the fields encapsulated within ReturnOverrides
+// This struct is used to alter the default response from an upstream server during request processing.
+// It allows changing the status code, headers, and the body of the response.
 
Add a method to check the validity of a SessionState instance.

Consider adding a method to easily retrieve and check the validity of the SessionState
based on Expires, QuotaRenews, and other time-based fields.

coprocess/coprocess_session_state.pb.go [326-344]

-type SessionState struct {
-    state         protoimpl.MessageState
-    sizeCache     protoimpl.SizeCache
-    unknownFields protoimpl.UnknownFields
-    ...
-    Expires int64 `protobuf:"varint,5,opt,name=expires,proto3" json:"expires,omitempty"`
-    ...
-    QuotaRenews int64 `protobuf:"varint,7,opt,name=quota_renews,json=quotaRenews,proto3" json:"quota_renews,omitempty"`
-    ...
+func (x *SessionState) IsValid() bool {
+    now := time.Now().Unix()
+    return now < x.Expires && now > x.QuotaRenews
 }
 
Simplify conditional assignments using a conditional expression.

Use a conditional expression to simplify the assignment of
_globals['DESCRIPTOR']._options. This makes the code more concise and easier to read.

coprocess/bindings/python/coprocess_object_pb2.py [26-27]

-if _descriptor._USE_C_DESCRIPTORS == False:
-  _globals['DESCRIPTOR']._options = None
+_globals['DESCRIPTOR']._options = None if _descriptor._USE_C_DESCRIPTORS == False else _globals['DESCRIPTOR']._options
 
Enhance the docstring of the DispatcherStub class to provide more detailed information about its purpose and functionality.

The docstring for the DispatcherStub class is incomplete and does not explain what the
class does beyond being an interface. It would be beneficial to provide a more detailed
description that explains the purpose and functionality of the class.

coprocess/bindings/python/coprocess_object_pb2_grpc.py [9-10]

-"""The service interface that must be implemented by the target language 
+"""The service interface that must be implemented by the target language to handle dispatch operations.
+
+This class provides stub methods to send requests to the server-side Dispatcher.
 """
 
Add logging before raising exceptions in Dispatch and DispatchEvent methods to aid in debugging and maintaining logs.

The exception handling in the Dispatch and DispatchEvent methods of the DispatcherServicer
class could be improved by logging the error before raising the exception. This would help
in debugging and maintaining logs of why the method was not implemented.

coprocess/bindings/python/coprocess_object_pb2_grpc.py [39]

+import logging
+logging.error('Method not implemented!')
 raise NotImplementedError('Method not implemented!')
 
Add warnings about the experimental status in the docstrings of Dispatch and DispatchEvent methods.

The Dispatcher class methods Dispatch and DispatchEvent are marked as experimental but
lack any warning or notice in their docstrings. It's important to explicitly state the
experimental status in the docstrings to inform users of potential instability.

coprocess/bindings/python/coprocess_object_pb2_grpc.py [69-70]

-"""The service interface that must be implemented by the target language 
+"""EXPERIMENTAL API: The service interface that must be implemented by the target language.
+
+Note: This API is experimental and may change or be removed in future releases.
 """
 
Performance
Implement context cancellation and timeouts for gRPC methods to enhance service reliability and performance.

Add context cancellation and timeout handling for the Dispatch and DispatchEvent methods
to improve the robustness and performance of the gRPC service.

coprocess/coprocess_object_grpc.pb.go [31-33]

+ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+defer cancel()
 Dispatch(ctx context.Context, in *Object, opts ...grpc.CallOption) (*Object, error)
 DispatchEvent(ctx context.Context, in *Event, opts ...grpc.CallOption) (*EventReply, error)
 
Maintainability
Rename Metadata and Spec to more descriptive names to improve code clarity and maintainability.

Use a more descriptive name for Metadata and Spec fields to reflect what kind of metadata
and specifications they are meant to store, enhancing code readability and
maintainability.

coprocess/coprocess_object.pb.go [39-42]

-// Contains the metadata. This is a dynamic field
-Metadata map[string]string `protobuf:"bytes,5,rep,name=metadata,proto3" json:"metadata,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-// Contains information about API definition, including APIID, OrgID and config_data
-Spec map[string]string `protobuf:"bytes,6,rep,name=spec,proto3" json:"spec,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+// Contains the API-related metadata. This is a dynamic field
+ApiMetadata map[string]string `protobuf:"bytes,5,rep,name=api_metadata,proto3" json:"api_metadata,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+// Contains detailed API specification information, including APIID, OrgID and config_data
+ApiSpec map[string]string `protobuf:"bytes,6,rep,name=api_spec,proto3" json:"api_spec,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
 
Remove deprecated fields from the SessionState struct.

Replace deprecated fields LastCheck and Allowance with more current alternatives or remove
them if they are no longer needed.

coprocess/coprocess_session_state.pb.go [331-334]

-// Deprecated
-LastCheck int64 `protobuf:"varint,1,opt,name=last_check,json=lastCheck,proto3" json:"last_check,omitempty"`
-// Deprecated, replaced by rate
-Allowance float64 `protobuf:"fixed64,2,opt,name=allowance,proto3" json:"allowance,omitempty"`
+// Fields removed due to deprecation
 
Refactor SessionState to separate authentication and rate limiting concerns.

To improve maintainability, consider refactoring the SessionState struct to separate
concerns, such as authentication and rate limiting into different structs.

coprocess/coprocess_session_state.pb.go [326-364]

+type AuthData struct {
+    Basic *BasicAuthData
+    JWT *JWTData
+}
+
+type RateLimiting struct {
+    Rate float64
+    Per float64
+}
+
 type SessionState struct {
     state         protoimpl.MessageState
     sizeCache     protoimpl.SizeCache
     unknownFields protoimpl.UnknownFields
-    ...
-    BasicAuthData *BasicAuthData `protobuf:"bytes,14,opt,name=basic_auth_data,json=basicAuthData,proto3" json:"basic_auth_data,omitempty"`
-    ...
-    Rate float64 `protobuf:"fixed64,3,opt,name=rate,proto3" json:"rate,omitempty"`
+    Auth AuthData
+    RateLimit RateLimiting
     ...
 }
 
Encapsulate descriptor option updates in a function to ensure integrity.

Replace the direct manipulation of _globals['DESCRIPTOR'] with a more robust method that
ensures the integrity of the descriptor. Directly setting _loaded_options and
_serialized_options can lead to unexpected behavior if the descriptor is used elsewhere in
the code. Consider encapsulating these operations in a function that checks for existing
options before modifying them.

coprocess/bindings/python/coprocess_common_pb2.py [22-24]

+def update_descriptor_options(descriptor, options=None, serialized_options=None):
+    if descriptor._loaded_options is None:
+        descriptor._loaded_options = options
+    if descriptor._serialized_options is None:
+        descriptor._serialized_options = serialized_options
+
 if not _descriptor._USE_C_DESCRIPTORS:
-  _globals['DESCRIPTOR']._loaded_options = None
-  _globals['DESCRIPTOR']._serialized_options = b'Z\n/coprocess'
+    update_descriptor_options(_globals['DESCRIPTOR'], None, b'Z\n/coprocess')
 
Use a helper function to apply serialized options to descriptors.

Instead of manually setting serialized options for each descriptor, create a helper
function that applies these settings based on a configuration dictionary. This approach
reduces redundancy and potential errors in setting serialized options manually.

coprocess/bindings/python/coprocess_object_pb2.py [29-32]

-_globals['_OBJECT_METADATAENTRY']._serialized_options = b'8\001'
-_globals['_OBJECT_SPECENTRY']._serialized_options = b'8\001'
+def apply_serialized_options(descriptor_map):
+    for key, value in descriptor_map.items():
+        _globals[key]._serialized_options = value
 
+serialized_options_map = {
+    '_OBJECT_METADATAENTRY': b'8\001',
+    '_OBJECT_SPECENTRY': b'8\001'
+}
+apply_serialized_options(serialized_options_map)
+
Refactor serialized bounds setting into a separate function.

Refactor the setting of serialized starts and ends for descriptors to a separate function
to improve code readability and maintainability. This function can take a descriptor name,
start, and end as parameters and apply these settings, reducing code duplication.

coprocess/bindings/python/coprocess_object_pb2.py [33-38]

-_globals['_OBJECT']._serialized_start=163
-_globals['_OBJECT']._serialized_end=552
-_globals['_OBJECT_METADATAENTRY']._serialized_start=460
-_globals['_OBJECT_METADATAENTRY']._serialized_end=507
-_globals['_OBJECT_SPECENTRY']._serialized_start=509
-_globals['_OBJECT_SPECENTRY']._serialized_end=552
+def set_serialized_bounds(descriptor_name, start, end):
+    _globals[descriptor_name]._serialized_start = start
+    _globals[descriptor_name]._serialized_end = end
 
+set_serialized_bounds('_OBJECT', 163, 552)
+set_serialized_bounds('_OBJECT_METADATAENTRY', 460, 507)
+set_serialized_bounds('_OBJECT_SPECENTRY', 509, 552)
+
Refine the repeated docstring across multiple classes to be more specific and avoid redundancy.

The repeated docstring phrase "The service interface that must be implemented by the
target language" is used in multiple classes (DispatcherStub, DispatcherServicer,
Dispatcher). It would be more maintainable to define this phrase once and reference it, or
to customize it per class to reflect specific responsibilities.

coprocess/bindings/python/coprocess_object_pb2_grpc.py [9-10]

-"""The service interface that must be implemented by the target language 
+"""The service interface for dispatch operations, to be implemented by the target language.
 """
 
Refactor the RPC method initialization in the DispatcherStub constructor to a separate method for better readability and maintainability.

The DispatcherStub class constructor initializes RPC methods directly in the constructor.
It would be cleaner and more maintainable to separate this logic into a private method,
improving the constructor's readability and maintainability.

coprocess/bindings/python/coprocess_object_pb2_grpc.py [18-27]

-self.Dispatch = channel.unary_unary(
-        '/coprocess.Dispatcher/Dispatch',
-        request_serializer=coprocess__object__pb2.Object.SerializeToString,
-        response_deserializer=coprocess__object__pb2.Object.FromString,
-        )
+self._initialize_methods(channel)
 
+def _initialize_methods(self, channel):
+    self.Dispatch = channel.unary_unary(
+            '/coprocess.Dispatcher/Dispatch',
+            request_serializer=coprocess__object__pb2.Object.SerializeToString,
+            response_deserializer=coprocess__object__pb2.Object.FromString,
+            )
+    self.DispatchEvent = channel.unary_unary(
+            '/coprocess.Dispatcher/DispatchEvent',
+            request_serializer=coprocess__object__pb2.Event.SerializeToString,
+            response_deserializer=coprocess__object__pb2.EventReply.FromString,
+            )
+
Security
Add validation for the Metadata map to enhance security.

Ensure that the Metadata map includes appropriate validation to prevent potential security
issues such as injection attacks.

coprocess/coprocess_session_state.pb.go [389]

+// Ensure metadata is validated to prevent injection
 Metadata map[string]string `protobuf:"bytes,23,rep,name=metadata,proto3" json:"metadata,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
 

✨ Improve tool usage guide:

Overview: The improve tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on a PR.

  • When commenting, to edit configurations related to the improve tool (pr_code_suggestions section), use the following template:
/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...
[pr_code_suggestions]
some_config1=...
some_config2=...

See the improve usage page for a comprehensive guide on using this tool.

github-actions[bot] avatar Apr 25 '24 15:04 github-actions[bot]

@dcs3spp CI is failing on this, also a lot to review. Can you follow godoc style comments in proto files, as discussed previously?

titpetric avatar May 21 '24 20:05 titpetric

:boom: CI tests failed :see_no_evil:

git-state

diff --git a/coprocess/coprocess_common.pb.go b/coprocess/coprocess_common.pb.go
index bdc0686..ccd0561 100644
--- a/coprocess/coprocess_common.pb.go
+++ b/coprocess/coprocess_common.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_mini_request_object.pb.go b/coprocess/coprocess_mini_request_object.pb.go
index 07136e3..184464b 100644
--- a/coprocess/coprocess_mini_request_object.pb.go
+++ b/coprocess/coprocess_mini_request_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_object.pb.go b/coprocess/coprocess_object.pb.go
index b3b4cd1..6fab2b8 100644
--- a/coprocess/coprocess_object.pb.go
+++ b/coprocess/coprocess_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_object_grpc.pb.go b/coprocess/coprocess_object_grpc.pb.go
index 8b48ff7..8423d03 100644
--- a/coprocess/coprocess_object_grpc.pb.go
+++ b/coprocess/coprocess_object_grpc.pb.go
@@ -8,6 +8,7 @@ package coprocess
 
 import (
 	context "context"
+
 	grpc "google.golang.org/grpc"
 	codes "google.golang.org/grpc/codes"
 	status "google.golang.org/grpc/status"
diff --git a/coprocess/coprocess_response_object.pb.go b/coprocess/coprocess_response_object.pb.go
index 87283f3..3970c8b 100644
--- a/coprocess/coprocess_response_object.pb.go
+++ b/coprocess/coprocess_response_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_return_overrides.pb.go b/coprocess/coprocess_return_overrides.pb.go
index ddee20b..f3e8454 100644
--- a/coprocess/coprocess_return_overrides.pb.go
+++ b/coprocess/coprocess_return_overrides.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_session_state.pb.go b/coprocess/coprocess_session_state.pb.go
index b542cc3..b1cbd61 100644
--- a/coprocess/coprocess_session_state.pb.go
+++ b/coprocess/coprocess_session_state.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (

Please look at the run or in the Checks tab.

github-actions[bot] avatar May 24 '24 09:05 github-actions[bot]

@titpetric I have updated comment style and fixed previous CI linting error. There is an error relating to Sonar Cloud?

dcs3spp avatar May 24 '24 10:05 dcs3spp

:boom: CI tests failed :see_no_evil:

git-state

diff --git a/coprocess/coprocess_common.pb.go b/coprocess/coprocess_common.pb.go
index 53ab3e8..6f82029 100644
--- a/coprocess/coprocess_common.pb.go
+++ b/coprocess/coprocess_common.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_mini_request_object.pb.go b/coprocess/coprocess_mini_request_object.pb.go
index 85f6f66..9bc0ca2 100644
--- a/coprocess/coprocess_mini_request_object.pb.go
+++ b/coprocess/coprocess_mini_request_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_object.pb.go b/coprocess/coprocess_object.pb.go
index 88fd8bf..9efbf14 100644
--- a/coprocess/coprocess_object.pb.go
+++ b/coprocess/coprocess_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_object_grpc.pb.go b/coprocess/coprocess_object_grpc.pb.go
index e6ed11a..7508908 100644
--- a/coprocess/coprocess_object_grpc.pb.go
+++ b/coprocess/coprocess_object_grpc.pb.go
@@ -8,6 +8,7 @@ package coprocess
 
 import (
 	context "context"
+
 	grpc "google.golang.org/grpc"
 	codes "google.golang.org/grpc/codes"
 	status "google.golang.org/grpc/status"
diff --git a/coprocess/coprocess_response_object.pb.go b/coprocess/coprocess_response_object.pb.go
index 40347aa..e7a7772 100644
--- a/coprocess/coprocess_response_object.pb.go
+++ b/coprocess/coprocess_response_object.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_return_overrides.pb.go b/coprocess/coprocess_return_overrides.pb.go
index 8bbe4a4..226c18d 100644
--- a/coprocess/coprocess_return_overrides.pb.go
+++ b/coprocess/coprocess_return_overrides.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (
diff --git a/coprocess/coprocess_session_state.pb.go b/coprocess/coprocess_session_state.pb.go
index b995595..25848eb 100644
--- a/coprocess/coprocess_session_state.pb.go
+++ b/coprocess/coprocess_session_state.pb.go
@@ -7,10 +7,11 @@
 package coprocess
 
 import (
-	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
-	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	reflect "reflect"
 	sync "sync"
+
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 )
 
 const (

Please look at the run or in the Checks tab.

github-actions[bot] avatar Jun 20 '24 16:06 github-actions[bot]

@titpetric I have updated comments in protobuf files for godoc style and ran schema-gen extract && schema-gen lint

dcs3spp avatar Jun 20 '24 16:06 dcs3spp

/release to release-5.3

titpetric avatar Jul 09 '24 10:07 titpetric

Working on it! Note that it can take a few minutes.

tykbot[bot] avatar Jul 09 '24 10:07 tykbot[bot]

@titpetric Seems like there is conflict and it require manual merge.

tykbot[bot] avatar Jul 09 '24 10:07 tykbot[bot]

Ok, I'll be copying the changes to release-5.3. This is done because it being a common documentation requirement (updating LTS docs). This PR doesn't represent a functional change, so we can still apply it. I'll link this PR from there.

titpetric avatar Jul 09 '24 10:07 titpetric