From edd9bd6f74c263d9365cfd0499262a9dcc2fa3bd Mon Sep 17 00:00:00 2001 From: Andrey Pleskach Date: Wed, 14 Apr 2021 15:06:07 +0200 Subject: [PATCH] Regen HTTP connector documentation --- docs/sink-connector-config-options.rst | 65 +++++++++++++- .../connect/http/config/HttpSinkConfig.java | 86 +++++++++++++------ .../connect/http/config/UrlValidator.java | 5 ++ 3 files changed, 130 insertions(+), 26 deletions(-) diff --git a/docs/sink-connector-config-options.rst b/docs/sink-connector-config-options.rst index f2935c1..7dc7e26 100644 --- a/docs/sink-connector-config-options.rst +++ b/docs/sink-connector-config-options.rst @@ -9,14 +9,14 @@ Connection The URL to send data to. * Type: string - * Valid Values: HTTP(S) ULRs + * Valid Values: HTTP(S) URL * Importance: high ``http.authorization.type`` The HTTP authorization type. * Type: string - * Valid Values: [none, static] + * Valid Values: [none, oauth2, static] * Importance: high * Dependents: ``http.headers.authorization`` @@ -34,6 +34,59 @@ Connection * Default: null * Importance: low +``oauth2.access.token.url`` + The URL to be used for fetching an access token. Client Credentials is the only supported grant type. + + * Type: string + * Default: null + * Valid Values: HTTP(S) URL + * Importance: high + * Dependents: ``oauth2.client.id``, ``oauth2.client.secret``, ``oauth2.client.authorization.mode``, ``oauth2.client.scope``, ``oauth2.response.token.property`` + +``oauth2.client.id`` + The client id used for fetching an access token. + + * Type: string + * Default: null + * Valid Values: OAuth2 client id + * Importance: high + * Dependents: ``oauth2.access.token.url``, ``oauth2.client.secret``, ``oauth2.client.authorization.mode``, ``oauth2.client.scope``, ``oauth2.response.token.property`` + +``oauth2.client.secret`` + The secret used for fetching an access token. + + * Type: password + * Default: null + * Importance: high + * Dependents: ``oauth2.access.token.url``, ``oauth2.client.id``, ``oauth2.client.authorization.mode``, ``oauth2.client.scope``, ``oauth2.response.token.property`` + +``oauth2.client.authorization.mode`` + Specifies how to encode ``client_id`` and ``client_secret`` in the OAuth2 authorization request. If set to ``header``, the credentials are encoded as an ``Authorization: Basic `` HTTP header. If set to ``url``, then ``client_id`` and ``client_secret`` are sent as URL encoded parameters. Default is ``header``. + + * Type: string + * Default: HEADER + * Valid Values: HEADER,URL + * Importance: medium + * Dependents: ``oauth2.access.token.url``, ``oauth2.client.id``, ``oauth2.client.secret``, ``oauth2.client.scope``, ``oauth2.response.token.property`` + +``oauth2.client.scope`` + The scope used for fetching an access token. + + * Type: string + * Default: null + * Valid Values: OAuth2 client scope + * Importance: low + * Dependents: ``oauth2.access.token.url``, ``oauth2.client.id``, ``oauth2.client.secret``, ``oauth2.client.authorization.mode``, ``oauth2.response.token.property`` + +``oauth2.response.token.property`` + The name of the JSON property containing the access token returned by the OAuth2 provider. Default value is ``access_token``. + + * Type: string + * Default: access_token + * Valid Values: OAuth2 response token + * Importance: low + * Dependents: ``oauth2.access.token.url``, ``oauth2.client.id``, ``oauth2.client.secret``, ``oauth2.client.authorization.mode``, ``oauth2.client.scope`` + Batching ^^^^^^^^ @@ -55,6 +108,14 @@ Batching Delivery ^^^^^^^^ +``kafka.retry.backoff.ms`` + The retry backoff in milliseconds. This config is used to notify Kafka Connect to retry delivering a message batch or performing recovery in case of transient failures. + + * Type: long + * Default: null + * Valid Values: null,[0, 86400000] + * Importance: medium + ``max.retries`` The maximum number of times to retry on errors when sending a batch before failing the task. diff --git a/src/main/java/io/aiven/kafka/connect/http/config/HttpSinkConfig.java b/src/main/java/io/aiven/kafka/connect/http/config/HttpSinkConfig.java index fe3c8b8..1d75d24 100644 --- a/src/main/java/io/aiven/kafka/connect/http/config/HttpSinkConfig.java +++ b/src/main/java/io/aiven/kafka/connect/http/config/HttpSinkConfig.java @@ -23,7 +23,6 @@ import java.util.List; import java.util.Map; import java.util.Objects; -import java.util.concurrent.TimeUnit; import org.apache.kafka.common.config.AbstractConfig; import org.apache.kafka.common.config.ConfigDef; @@ -157,35 +156,49 @@ public boolean visible(final String name, final Map parsedConfig null, new UrlValidator(true), ConfigDef.Importance.HIGH, - "The URL to be used for fetching access token. " - + "Client Credentials is only supported grand type.", + "The URL to be used for fetching an access token. " + + "Client Credentials is the only supported grant type.", CONNECTION_GROUP, groupCounter++, ConfigDef.Width.LONG, - OAUTH2_ACCESS_TOKEN_URL_CONFIG + OAUTH2_ACCESS_TOKEN_URL_CONFIG, + List.of(OAUTH2_CLIENT_ID_CONFIG, OAUTH2_CLIENT_SECRET_CONFIG, + OAUTH2_CLIENT_AUTHORIZATION_MODE_CONFIG, OAUTH2_CLIENT_SCOPE_CONFIG, + OAUTH2_RESPONSE_TOKEN_PROPERTY_CONFIG) ); configDef.define( OAUTH2_CLIENT_ID_CONFIG, ConfigDef.Type.STRING, null, - new ConfigDef.NonEmptyStringWithoutControlChars(), + new ConfigDef.NonEmptyStringWithoutControlChars() { + @Override + public String toString() { + return "OAuth2 client id"; + } + }, ConfigDef.Importance.HIGH, - "The client id used for fetching access token.", + "The client id used for fetching an access token.", CONNECTION_GROUP, groupCounter++, ConfigDef.Width.LONG, - OAUTH2_CLIENT_ID_CONFIG + OAUTH2_CLIENT_ID_CONFIG, + List.of(OAUTH2_ACCESS_TOKEN_URL_CONFIG, OAUTH2_CLIENT_SECRET_CONFIG, + OAUTH2_CLIENT_AUTHORIZATION_MODE_CONFIG, + OAUTH2_CLIENT_SCOPE_CONFIG, OAUTH2_RESPONSE_TOKEN_PROPERTY_CONFIG) ); configDef.define( OAUTH2_CLIENT_SECRET_CONFIG, ConfigDef.Type.PASSWORD, null, ConfigDef.Importance.HIGH, - "The secret used for fetching access token.", + "The secret used for fetching an access token.", CONNECTION_GROUP, groupCounter++, ConfigDef.Width.LONG, - OAUTH2_CLIENT_SECRET_CONFIG + OAUTH2_CLIENT_SECRET_CONFIG, + List.of(OAUTH2_ACCESS_TOKEN_URL_CONFIG, OAUTH2_CLIENT_ID_CONFIG, + OAUTH2_CLIENT_AUTHORIZATION_MODE_CONFIG, + OAUTH2_CLIENT_SCOPE_CONFIG, OAUTH2_RESPONSE_TOKEN_PROPERTY_CONFIG) ); configDef.define( OAUTH2_CLIENT_AUTHORIZATION_MODE_CONFIG, @@ -207,42 +220,63 @@ public void ensureValid(final String name, final Object value) { "supported values are: " + OAuth2AuthorizationMode.OAUTH2_AUTHORIZATION_MODES); } } + + @Override + public String toString() { + return String.join(",", OAuth2AuthorizationMode.OAUTH2_AUTHORIZATION_MODES); + } }, ConfigDef.Importance.MEDIUM, - "Specifies how to encode client_id and client_secret in the OAuth2 authorization request. " - + "If set to 'header', the credentials are encoded as an " - + "'Authorization: Basic ' HTTP header. " - + "If set to ‘url’, then client_id and client_secret are sent as URL encoded parameters. " - + "Default is 'header'", + "Specifies how to encode ``client_id`` and ``client_secret`` in the OAuth2 authorization request. " + + "If set to ``header``, the credentials are encoded as an " + + "``Authorization: Basic `` HTTP header. " + + "If set to ``url``, then ``client_id`` and ``client_secret`` " + + "are sent as URL encoded parameters. Default is ``header``.", CONNECTION_GROUP, groupCounter++, ConfigDef.Width.LONG, - OAUTH2_CLIENT_AUTHORIZATION_MODE_CONFIG + OAUTH2_CLIENT_AUTHORIZATION_MODE_CONFIG, + List.of(OAUTH2_ACCESS_TOKEN_URL_CONFIG, OAUTH2_CLIENT_ID_CONFIG, OAUTH2_CLIENT_SECRET_CONFIG, + OAUTH2_CLIENT_SCOPE_CONFIG, OAUTH2_RESPONSE_TOKEN_PROPERTY_CONFIG) ); configDef.define( OAUTH2_CLIENT_SCOPE_CONFIG, ConfigDef.Type.STRING, null, - new ConfigDef.NonEmptyStringWithoutControlChars(), + new ConfigDef.NonEmptyStringWithoutControlChars() { + @Override + public String toString() { + return "OAuth2 client scope"; + } + }, ConfigDef.Importance.LOW, - "The scope used for fetching access token.", + "The scope used for fetching an access token.", CONNECTION_GROUP, groupCounter++, ConfigDef.Width.LONG, - OAUTH2_CLIENT_SCOPE_CONFIG + OAUTH2_CLIENT_SCOPE_CONFIG, + List.of(OAUTH2_ACCESS_TOKEN_URL_CONFIG, OAUTH2_CLIENT_ID_CONFIG, OAUTH2_CLIENT_SECRET_CONFIG, + OAUTH2_CLIENT_AUTHORIZATION_MODE_CONFIG, OAUTH2_RESPONSE_TOKEN_PROPERTY_CONFIG) ); configDef.define( OAUTH2_RESPONSE_TOKEN_PROPERTY_CONFIG, ConfigDef.Type.STRING, "access_token", - new ConfigDef.NonEmptyStringWithoutControlChars(), + new ConfigDef.NonEmptyStringWithoutControlChars() { + @Override + public String toString() { + return "OAuth2 response token"; + } + }, ConfigDef.Importance.LOW, - "The name of the JSON property containing the access token returned by the OAuth2 provider. " - + "Default value is 'access_token'.", + "The name of the JSON property containing the access token returned " + + "by the OAuth2 provider. Default value is ``access_token``.", CONNECTION_GROUP, groupCounter++, ConfigDef.Width.LONG, - OAUTH2_RESPONSE_TOKEN_PROPERTY_CONFIG + OAUTH2_RESPONSE_TOKEN_PROPERTY_CONFIG, + List.of(OAUTH2_ACCESS_TOKEN_URL_CONFIG, OAUTH2_CLIENT_ID_CONFIG, OAUTH2_CLIENT_SECRET_CONFIG, + OAUTH2_CLIENT_AUTHORIZATION_MODE_CONFIG, OAUTH2_CLIENT_SCOPE_CONFIG) ); } @@ -298,12 +332,16 @@ public void ensureValid(final String name, final Object value) { "Value must be no more than " + MAXIMUM_BACKOFF_POLICY + " (24 hours)"); } } + + @Override + public String toString() { + return String.join(",", List.of("null", "[0, " + MAXIMUM_BACKOFF_POLICY + "]")); + } }, ConfigDef.Importance.MEDIUM, "The retry backoff in milliseconds. " + "This config is used to notify Kafka Connect to retry delivering a message batch or " - + "performing recovery in case of transient exceptions. Maximum value is " - + TimeUnit.HOURS.toMillis(24) + " (24 hours).", + + "performing recovery in case of transient failures.", DELIVERY_GROUP, groupCounter++, ConfigDef.Width.NONE, diff --git a/src/main/java/io/aiven/kafka/connect/http/config/UrlValidator.java b/src/main/java/io/aiven/kafka/connect/http/config/UrlValidator.java index 63f1127..31ed62b 100644 --- a/src/main/java/io/aiven/kafka/connect/http/config/UrlValidator.java +++ b/src/main/java/io/aiven/kafka/connect/http/config/UrlValidator.java @@ -52,4 +52,9 @@ public void ensureValid(final String name, final Object value) { } } + @Override + public String toString() { + return "HTTP(S) URL"; + } + }