github-actions[bot]
commented
1 month ago API Changes
--- prev.txt 2024-07-08 20:55:58.960473305 +0000
+++ current.txt 2024-07-08 20:55:56.192467871 +0000
@@ -2377,10 +2377,12 @@
TYPES
type APIDef struct {
- OAS *OAS
+ // OAS contains the OAS API definition.
+ OAS *OAS
+ // Classic contains the Classic API definition.
Classic *apidef.APIDefinition
}
- APIDef is struct to hold both OAS and Classic forms of an API definition.
+ APIDef holds both OAS and Classic forms of an API definition.
type Allowance struct {
// Enabled is a boolean flag, if set to `true`, then individual allowances (allow, block, ignore) will be enforced.
@@ -2525,7 +2527,8 @@
type Basic struct {
// Enabled activates the basic authentication mode.
// Tyk classic API definition: `use_basic_auth`
- Enabled bool `bson:"enabled" json:"enabled"` // required
+ Enabled bool `bson:"enabled" json:"enabled"` // required
+ // AuthSources contains the source for HTTP Basic Auth credentials.
AuthSources `bson:",inline" json:",inline"`
// DisableCaching disables the caching of basic authentication key.
// Tyk classic API definition: `basic_auth.disable_caching`
@@ -2877,6 +2880,8 @@
that were previously used to represent the same data.
type EndpointPostPlugins []EndpointPostPlugin
+ EndpointPostPlugins is a list of EndpointPostPlugins. It's used where
+ multiple plugins can be run.
func (e EndpointPostPlugins) ExtractTo(meta *apidef.GoPluginMeta)
ExtractTo extracts *EndpointPostPlugin to *apidef.GoPluginMeta.
@@ -2900,10 +2905,16 @@
Fill fills *EnforceTimeout from apidef.HardTimeoutMeta.
type ExternalOAuth struct {
- Enabled bool `bson:"enabled" json:"enabled"` // required
+ // Enabled activates external oauth functionality.
+ Enabled bool `bson:"enabled" json:"enabled"` // required
+
+ // AuthSources configures the source for the authentication token.
AuthSources `bson:",inline" json:",inline"`
- Providers []OAuthProvider `bson:"providers" json:"providers"` // required
+
+ // Providers is used to configure OAuth providers.
+ Providers []OAuthProvider `bson:"providers" json:"providers"` // required
}
+ ExternalOAuth holds configuration for an external OAuth provider.
type ExtractCredentialsFromBody struct {
// Enabled activates extracting credentials from body.
@@ -2942,7 +2953,7 @@
type GatewayTags struct {
// Enabled activates use of segment tags.
Enabled bool `bson:"enabled" json:"enabled"`
- // Tags is a list of segment tags
+ // Tags contains a list of segment tags.
Tags []string `bson:"tags" json:"tags"`
}
GatewayTags holds a list of segment tags that should apply for a gateway.
@@ -2973,7 +2984,7 @@
// Deprecated: Use PostAuthenticationPlugins instead.
PostAuthenticationPlugin *PostAuthenticationPlugin `bson:"postAuthenticationPlugin,omitempty" json:"postAuthenticationPlugin,omitempty"`
- // PostAuthenticationPlugin contains configuration related to the custom plugin that is run immediately after authentication.
+ // PostAuthenticationPlugins contains configuration related to the custom plugin that is run immediately after authentication.
// Tyk classic API definition: `custom_middleware.post_key_auth`.
PostAuthenticationPlugins CustomPlugins `bson:"postAuthenticationPlugins,omitempty" json:"postAuthenticationPlugins,omitempty"`
@@ -2985,7 +2996,7 @@
// Tyk classic API definition: `custom_middleware.post`.
PostPlugins CustomPlugins `bson:"postPlugins,omitempty" json:"postPlugins,omitempty"`
- // Deprecated: ResponsePlugin contains configuration related to the custom plugin that is run during processing of the response from the upstream service.
+ // ResponsePlugin contains configuration related to the custom plugin that is run during processing of the response from the upstream service.
// Deprecated: Use ResponsePlugins instead.
ResponsePlugin *ResponsePlugin `bson:"responsePlugin,omitempty" json:"responsePlugin,omitempty"`
@@ -3162,6 +3173,7 @@
// Cache is the caching mechanism for introspection responses.
Cache *IntrospectionCache `bson:"cache,omitempty" json:"cache,omitempty"`
}
+ Introspection holds configuration for OAuth token introspection.
func (i *Introspection) ExtractTo(intros *apidef.Introspection)
@@ -3174,25 +3186,73 @@
// For introspection caching, it is suggested to use a short interval.
Timeout int64 `bson:"timeout" json:"timeout"`
}
+ IntrospectionCache holds configuration for caching introspection requests.
func (c *IntrospectionCache) ExtractTo(cache *apidef.IntrospectionCache)
func (c *IntrospectionCache) Fill(cache apidef.IntrospectionCache)
type JWT struct {
- Enabled bool `bson:"enabled" json:"enabled"` // required
- AuthSources `bson:",inline" json:",inline"`
- Source string `bson:"source,omitempty" json:"source,omitempty"`
- SigningMethod string `bson:"signingMethod,omitempty" json:"signingMethod,omitempty"`
- IdentityBaseField string `bson:"identityBaseField,omitempty" json:"identityBaseField,omitempty"`
- SkipKid bool `bson:"skipKid,omitempty" json:"skipKid,omitempty"`
- PolicyFieldName string `bson:"policyFieldName,omitempty" json:"policyFieldName,omitempty"`
- ClientBaseField string `bson:"clientBaseField,omitempty" json:"clientBaseField,omitempty"`
- Scopes *Scopes `bson:"scopes,omitempty" json:"scopes,omitempty"`
- DefaultPolicies []string `bson:"defaultPolicies,omitempty" json:"defaultPolicies,omitempty"`
- IssuedAtValidationSkew uint64 `bson:"issuedAtValidationSkew,omitempty" json:"issuedAtValidationSkew,omitempty"`
- NotBeforeValidationSkew uint64 `bson:"notBeforeValidationSkew,omitempty" json:"notBeforeValidationSkew,omitempty"`
- ExpiresAtValidationSkew uint64 `bson:"expiresAtValidationSkew,omitempty" json:"expiresAtValidationSkew,omitempty"`
+ // Enabled activates the basic authentication mode.
+ //
+ // Tyk classic API definition: `enable_jwt`
+ Enabled bool `bson:"enabled" json:"enabled"` // required
+
+ // AuthSources configures the source for the JWT.
+ AuthSources `bson:",inline" json:",inline"`
+
+ // Source contains the source for the JWT.
+ //
+ // Tyk classic API definition: `jwt_source`
+ Source string `bson:"source,omitempty" json:"source,omitempty"`
+
+ // SigningMethod contains the signing method to use for the JWT.
+ //
+ // Tyk classic API definition: `jwt_signing_method`
+ SigningMethod string `bson:"signingMethod,omitempty" json:"signingMethod,omitempty"`
+
+ // IdentityBaseField specifies the claim name uniquely identifying the subject of the JWT.
+ // The identity fields that are checked in order are: `kid`, IdentityBaseField, `sub`.
+ //
+ // Tyk classic API definition: `jwt_identity_base_field`
+ IdentityBaseField string `bson:"identityBaseField,omitempty" json:"identityBaseField,omitempty"`
+
+ // SkipKid controls skipping using the `kid` claim from a JWT (default behaviour).
+ // When this is true, the field configured in IdentityBaseField is checked first.
+ //
+ // Tyk classic API definition: `jwt_skip_kid`
+ SkipKid bool `bson:"skipKid,omitempty" json:"skipKid,omitempty"`
+
+ // PolicyFieldName is a configurable claim name from which a policy ID is extracted.
+ // The policy is applied to the session as a base policy.
+ //
+ // Tyk classic API definition: `jwt_policy_field_name`
+ PolicyFieldName string `bson:"policyFieldName,omitempty" json:"policyFieldName,omitempty"`
+
+ // ClientBaseField is used when PolicyFieldName is not provided. It will get
+ // a session key and use the policies from that. The field ensures that requests
+ // use the same session.
+ //
+ // Tyk classic API definition: `jwt_client_base_field`
+ ClientBaseField string `bson:"clientBaseField,omitempty" json:"clientBaseField,omitempty"`
+
+ // Scopes holds the scope to policy mappings for a claim name.
+ Scopes *Scopes `bson:"scopes,omitempty" json:"scopes,omitempty"`
+
+ // DefaultPolicies is a list of policy IDs that apply to the session.
+ //
+ // Tyk classic API definition: `jwt_default_policies`
+ DefaultPolicies []string `bson:"defaultPolicies,omitempty" json:"defaultPolicies,omitempty"`
+
+ // IssuedAtValidationSkew contains the duration in seconds for which token issuance can predate the current time during the request.
+ IssuedAtValidationSkew uint64 `bson:"issuedAtValidationSkew,omitempty" json:"issuedAtValidationSkew,omitempty"`
+
+ // NotBeforeValidationSkew contains the duration in seconds for which token validity can predate the current time during the request.
+ NotBeforeValidationSkew uint64 `bson:"notBeforeValidationSkew,omitempty" json:"notBeforeValidationSkew,omitempty"`
+
+ // ExpiresAtValidationSkew contains the duration in seconds for which the token can be expired before we consider it expired.
+ ExpiresAtValidationSkew uint64 `bson:"expiresAtValidationSkew,omitempty" json:"expiresAtValidationSkew,omitempty"`
+
// IDPClientIDMappingDisabled prevents Tyk from automatically detecting the use of certain IDPs based on standard claims
// that they include in the JWT: `client_id`, `cid`, `clientId`. Setting this flag to `true` disables the mapping and avoids
// accidentally misidentifying the use of one of these IDPs if one of their standard values is configured in your JWT.
@@ -3204,7 +3264,7 @@
Import populates *JWT based on arguments.
type JWTValidation struct {
- // Enabled activates OAuth access token validation by introspection to a third party.
+ // Enabled activates OAuth access token validation.
Enabled bool `bson:"enabled" json:"enabled"`
// SigningMethod to verify signing method used in jwt - allowed values HMAC/RSA/ECDSA.
@@ -3229,6 +3289,8 @@
// ExpiresAtValidationSkew is the clock skew to be considered while validating the exp claim.
ExpiresAtValidationSkew uint64 `bson:"expiresAtValidationSkew,omitempty" json:"expiresAtValidationSkew,omitempty"`
}
+ JWTValidation holds configuration for validating access tokens by inspecing
+ them against a third party API, usually one provided by the IDP.
func (j *JWTValidation) ExtractTo(jwt *apidef.JWTValidation)
@@ -3368,12 +3430,23 @@
UpdateServers sets or updates the first servers URL if it matches oldAPIURL.
type OAuth struct {
- Enabled bool `bson:"enabled" json:"enabled"` // required
- AuthSources `bson:",inline" json:",inline"`
+ // Enabled activates the OAuth middleware.
+ Enabled bool `bson:"enabled" json:"enabled"` // required
+
+ // AuthSources configures the sources for OAuth credentials.
+ AuthSources `bson:",inline" json:",inline"`
+
+ // AllowedAuthorizeTypes is an array of OAuth authorization types.
AllowedAuthorizeTypes []osin.AuthorizeRequestType `bson:"allowedAuthorizeTypes,omitempty" json:"allowedAuthorizeTypes,omitempty"`
- RefreshToken bool `bson:"refreshToken,omitempty" json:"refreshToken,omitempty"`
- AuthLoginRedirect string `bson:"authLoginRedirect,omitempty" json:"authLoginRedirect,omitempty"`
- Notifications *Notifications `bson:"notifications,omitempty" json:"notifications,omitempty"`
+
+ // RefreshToken enables clients using a refresh token to get a new bearer access token.
+ RefreshToken bool `bson:"refreshToken,omitempty" json:"refreshToken,omitempty"`
+
+ // AuthLoginRedirect configures a URL to redirect to after a successful login.
+ AuthLoginRedirect string `bson:"authLoginRedirect,omitempty" json:"authLoginRedirect,omitempty"`
+
+ // Notifications configures a URL trigger on key changes.
+ Notifications *Notifications `bson:"notifications,omitempty" json:"notifications,omitempty"`
}
OAuth configures the OAuth middleware.
@@ -3381,9 +3454,13 @@
Import populates *OAuth from it's arguments.
type OAuthProvider struct {
- JWT *JWTValidation `bson:"jwt,omitempty" json:"jwt,omitempty"`
+ // JWT configures JWT validation.
+ JWT *JWTValidation `bson:"jwt,omitempty" json:"jwt,omitempty"`
+ // Introspection configures token introspection.
Introspection *Introspection `bson:"introspection,omitempty" json:"introspection,omitempty"`
}
+ OAuthProvider holds the configuration for validation and introspection of
+ OAuth tokens.
type OIDC struct {
// Enabled activates the OIDC authentication mode.
@@ -3418,6 +3495,7 @@
type OldOAS struct {
openapifork.T
}
+ OldOAS serves for data model migration/conversion purposes (gorm).
func (o *OldOAS) ConvertToNewerOAS() (*OAS, error)
ConvertToNewerOAS converts a deprecated OldOAS object to the newer OAS
@@ -3496,14 +3574,23 @@
Operations holds Operation definitions.
type Path struct {
- Delete *Plugins `bson:"DELETE,omitempty" json:"DELETE,omitempty"`
- Get *Plugins `bson:"GET,omitempty" json:"GET,omitempty"`
- Head *Plugins `bson:"HEAD,omitempty" json:"HEAD,omitempty"`
+ // Delete holds plugin configuration for DELETE requests.
+ Delete *Plugins `bson:"DELETE,omitempty" json:"DELETE,omitempty"`
+ // Get holds plugin configuration for GET requests.
+ Get *Plugins `bson:"GET,omitempty" json:"GET,omitempty"`
+ // Head holds plugin configuration for HEAD requests.
+ Head *Plugins `bson:"HEAD,omitempty" json:"HEAD,omitempty"`
+ // Options holds plugin configuration for OPTIONS requests.
Options *Plugins `bson:"OPTIONS,omitempty" json:"OPTIONS,omitempty"`
- Patch *Plugins `bson:"PATCH,omitempty" json:"PATCH,omitempty"`
- Post *Plugins `bson:"POST,omitempty" json:"POST,omitempty"`
- Put *Plugins `bson:"PUT,omitempty" json:"PUT,omitempty"`
- Trace *Plugins `bson:"TRACE,omitempty" json:"TRACE,omitempty"`
+ // Patch holds plugin configuration for PATCH requests.
+ Patch *Plugins `bson:"PATCH,omitempty" json:"PATCH,omitempty"`
+ // Post holds plugin configuration for POST requests.
+ Post *Plugins `bson:"POST,omitempty" json:"POST,omitempty"`
+ // Put holds plugin configuration for PUT requests.
+ Put *Plugins `bson:"PUT,omitempty" json:"PUT,omitempty"`
+ // Trace holds plugin configuration for TRACE requests.
+ Trace *Plugins `bson:"TRACE,omitempty" json:"TRACE,omitempty"`
+ // Connect holds plugin configuration for CONNECT requests.
Connect *Plugins `bson:"CONNECT,omitempty" json:"CONNECT,omitempty"`
}
Path holds plugin configurations for HTTP method verbs.
@@ -3605,7 +3692,7 @@
// Block request by allowance.
Block *Allowance `bson:"block,omitempty" json:"block,omitempty"`
- // Ignore authentication on request by allowance.
+ // IgnoreAuthentication ignores authentication on request by allowance.
IgnoreAuthentication *Allowance `bson:"ignoreAuthentication,omitempty" json:"ignoreAuthentication,omitempty"`
// TransformRequestMethod allows you to transform the method of a request.
@@ -3960,14 +4047,32 @@
ServiceDiscoveryCache holds configuration for caching ServiceDiscovery data.
type Signature struct {
- Enabled bool `bson:"enabled" json:"enabled"` // required
- Algorithm string `bson:"algorithm,omitempty" json:"algorithm,omitempty"`
- Header string `bson:"header,omitempty" json:"header,omitempty"`
- Query AuthSource `bson:"query,omitempty" json:"query,omitempty"`
- Secret string `bson:"secret,omitempty" json:"secret,omitempty"`
- AllowedClockSkew int64 `bson:"allowedClockSkew,omitempty" json:"allowedClockSkew,omitempty"`
- ErrorCode int `bson:"errorCode,omitempty" json:"errorCode,omitempty"`
- ErrorMessage string `bson:"errorMessage,omitempty" json:"errorMessage,omitempty"`
+ // Enabled activates signature validation.
+ // Tyk classic API definition: `auth_configs[X].validate_signature`.
+ Enabled bool `bson:"enabled" json:"enabled"` // required
+ // Algorithm is the signature method to use.
+ // Tyk classic API definition: `auth_configs[X].signature.algorithm`.
+ Algorithm string `bson:"algorithm,omitempty" json:"algorithm,omitempty"`
+ // Header is the name of the header to consume.
+ // Tyk classic API definition: `auth_configs[X].signature.header`.
+ Header string `bson:"header,omitempty" json:"header,omitempty"`
+ // Query is the name of the query parameter to consume.
+ // Tyk classic API definition: `auth_configs[X].signature.use_param/param_name`.
+ Query AuthSource `bson:"query,omitempty" json:"query,omitempty"`
+ // Secret is the signing secret used for signature validation.
+ // Tyk classic API definition: `auth_configs[X].signature.secret`.
+ Secret string `bson:"secret,omitempty" json:"secret,omitempty"`
+ // AllowedClockSkew configures a grace period in seconds during which an expired token is still valid.
+ // Tyk classic API definition: `auth_configs[X].signature.allowed_clock_skew`.
+ AllowedClockSkew int64 `bson:"allowedClockSkew,omitempty" json:"allowedClockSkew,omitempty"`
+ // ErrorCode configures the HTTP response code for a validation failure.
+ // If unconfigured, a HTTP 401 Unauthorized status code will be emitted.
+ // Tyk classic API definition: `auth_configs[X].signature.error_code`.
+ ErrorCode int `bson:"errorCode,omitempty" json:"errorCode,omitempty"`
+ // ErrorMessage configures the error message that is emitted on validation failure.
+ // A default error message is emitted if unset.
+ // Tyk classic API definition: `auth_configs[X].signature.error_message`.
+ ErrorMessage string `bson:"errorMessage,omitempty" json:"errorMessage,omitempty"`
}
Signature holds the configuration for signature validation.
@@ -4098,14 +4203,23 @@
Fill fills *TransformRequestMethod from apidef.MethodTransformMeta.
type TykExtensionConfigParams struct {
- UpstreamURL string
- ListenPath string
- CustomDomain string
- ApiID string
- Authentication *bool
- AllowList *bool
+ // UpstreamURL configures the upstream URL.
+ UpstreamURL string
+ // ListenPath configures the listen path.
+ ListenPath string
+ // CustomDomain configures the domain name.
+ CustomDomain string
+ // ApiID is the API ID.
+ ApiID string
+
+ // Authentication is true if the API configures authentication.
+ Authentication *bool
+ // AllowList is true if the API configures an allow list.
+ AllowList *bool
+ // ValidateRequest is true if the API enables request validation.
ValidateRequest *bool
- MockResponse *bool
+ // MockResponse is true if a mocked response is configured.
+ MockResponse *bool
}
TykExtensionConfigParams holds the essential configuration required for the
Tyk Extension schema.
@@ -4144,8 +4258,8 @@
type URLRewriteCondition string
URLRewriteCondition defines the matching mode for an URL rewrite rules.
- - Value `any` means any of the defined trigger rules may match - Value `all`
- means all the defined trigger rules must match
+ - Value `any` means any of the defined trigger rules may match. - Value
+ `all` means all the defined trigger rules must match.
type URLRewriteInput string
URLRewriteInput defines the input for an URL rewrite rule.
@@ -4159,6 +4273,8 @@
match pattern against request body - `requestContext`, match pattern against
request context
+ The default `url` is used as the input source.
+
func (i URLRewriteInput) Err() error
Err returns an error if the type value is invalid, nil otherwise.
@@ -4170,17 +4286,6 @@
type URLRewriteRule struct {
// In specifies one of the valid inputs for URL rewriting.
- // By default, it uses `url` as the input source.
- //
- // The following values are valid:
- //
- // - `url`, match pattern against URL
- // - `query`, match pattern against named query parameter value
- // - `path`, match pattern against named path parameter value
- // - `header`, match pattern against named header value
- // - `sessionMetadata`, match pattern against session metadata
- // - `requestBody`, match pattern against request body
- // - `requestContext`, match pattern against request context
In URLRewriteInput `bson:"in" json:"in"`
// Name is the index in the value declared inside `in`.
@@ -4203,10 +4308,7 @@
URLRewriteRule represents a rewrite matching rules.
type URLRewriteTrigger struct {
- // Condition indicates the logical combination that will be applied to the rules for an advanced trigger:
- //
- // - Value `any` means any of the defined trigger rules may match
- // - Value `all` means all the defined trigger rules must match
+ // Condition indicates the logical combination that will be applied to the rules for an advanced trigger.
Condition URLRewriteCondition `bson:"condition" json:"condition"`
// Rules contain individual checks that are combined according to the
sonarcloud[bot]
User description
TT-11032 Godoc CI lint action, config and apidef/oas (#6386)
User description
We generate outputs based on godocs from two different packages:
/configthat provides configuration for the gateway/apidef/oasthat documents the OAS schemaTwo lint commands have been added into the taskfile, and
apidef-oas:lintis enforced:As we provide user facing documentation, it should conform to our documentation standards. This PR should serve as the template for correcting godocs over these areas, as the CI change ensures we don't regress over time.
This aims to fix the apidef/oas state with missing documentation.
PR Type
Enhancement, Tests
Description
configandapidef-oastaskfiles.linttask in the main Taskfile to includeconfig:lintandapidef-oas:lint.apidef/oaswith tasks for running tests, linting, and updating dependencies.configwith tasks for running tests, linting, and updating dependencies.Changes walkthrough 📝
Taskfile.yml
Update Taskfile to include config and OAS schema lintingTaskfile.yml
configandapidef-oastaskfiles.linttask to includeconfig:lintandapidef-oas:lint.Taskfile.yml
Add Taskfile for OAS schema tasksapidef/oas/Taskfile.yml
apidef/oas.Taskfile.yml
Add Taskfile for config tasksconfig/Taskfile.yml
config.Co-authored-by: Tit Petric tit@tyk.io
PR Type
Enhancement, Tests
Description
apidef/oaspackage to improve documentation and link fields to corresponding Tyk classic API definitions.configandapidef-oas.apidef/oasandconfigwith tasks for running tests, linting, and updating dependencies.Changes walkthrough 📝
8 files
authentication.go
Add detailed comments to Signature struct fieldsapidef/oas/authentication.go
Signaturestruct.default.go
Add detailed comments to TykExtensionConfigParams struct fieldsapidef/oas/default.go
TykExtensionConfigParamsstruct.
middleware.go
Add detailed comments to middleware-related structs and typesapidef/oas/middleware.go
Globalstruct.Pathstruct.Pluginsstruct.EndpointPostPluginstype.oas.go
Add detailed comments to APIDef struct fieldsapidef/oas/oas.go - Added detailed comments for each field in the `APIDef` struct.
old_oas.go
Add comment to OldOAS structapidef/oas/old_oas.go - Added a comment for the `OldOAS` struct.
security.go
Add detailed comments to security-related structsapidef/oas/security.go
JWT,Basic,OAuth,OAuthProvider,JWTValidation,Introspection,IntrospectionCache, andExternalOAuthstructs.server.go
Add detailed comments to GatewayTags struct fieldsapidef/oas/server.go
GatewayTagsstruct.url_rewrite.go
Add detailed comments to URL rewrite-related structsapidef/oas/url_rewrite.go
URLRewriteInput,URLRewriteCondition,URLRewriteTrigger, andURLRewriteRulestructs.3 files
Taskfile.yml
Update Taskfile to include new lint tasks and configurationsTaskfile.yml
configandapidef-oas.linttask to includeconfig:lintandapidef-oas:lint.Taskfile.yml
Add Taskfile for apidef/oas with test and lint tasksapidef/oas/Taskfile.yml
apidef/oaswith tasks for running tests,linting, and updating dependencies.
Taskfile.yml
Add Taskfile for config with test and lint tasksconfig/Taskfile.yml
configwith tasks for running tests,linting, and updating dependencies.