Http¶

The http listens for incoming connections, accepting HTTP/1.1 POST requests and processing them accordingly.

The source emits the decoded request body. The whitelisted request headers are written to the stage-scoped {@link org.voltdb.stream.api.StashContext} when the headers field is configured with at least one entry; an empty/unset headers field means no headers are deserialised or stashed.

Available stash entries:

Entry	Java (typed key)	YAML / JS / Python (name)	Runtime type
Headers	`HttpStashKeys.HEADERS`	`source.http.headers`	`Map<String, String>`

JAVAYAML

HttpSourceConfig<CharSequence> config = HttpSourceConfigBuilder
         .<CharSequence>builder()
         .withAddress("0.0.0.0", 8080)
         .withExceptionHandler(...)
         .withDecoder(Decoders.toCharSequenceDecoder())
         .build();

source:
   http:
     address: '0.0.0.0:8080'
     path: "/basket"
     expectedContentTypes:
       - application/json
       - text/plain
     headers:
       - Content-Type
       - CustomHeader
     readIdleTimeout: PT1M

Java dependency management¶

Add this declaration to your dependency management system to access the configuration DSL for this plugin in Java.

MavenGradle

<dependency>
    <groupId>org.voltdb</groupId>
    <artifactId>volt-stream-plugin-http-api</artifactId>
    <version>1.8.0</version>
</dependency>

implementation group: 'org.voltdb', name: 'volt-stream-plugin-http-api', version: '1.8.0'

Properties¶

`address`¶

If no address is provided, the server defaults to 0.0.0.0, which binds it to all available network interfaces.

Required.

Type: object

Default value: 0.0.0.0

Fields of address:

`address.host`¶

Type: string

`address.port`¶

Type: number

`address.hasBracketlessColons`¶

Type: boolean

`decoder`¶

Decoder applied to incoming data. Converts input into a usable format. For built-in decoder implementations, see org.voltdb.stream.api.network.Decoders.

Required.

Type: object

`path`¶

The URI path on which the HTTP server listens for incoming requests. For example, '/' for the root context, or '/basket' for a specific subpath.

Type: string

Default value: /

`headers`¶

A set of header names to extract from the HTTP request and write to the stash context. Leave empty (the default) to skip header deserialisation.

Type: array

`maxContentSize`¶

Specifies the maximum size (in bytes) of incoming content that the server will accept. The default limit is 1 MB to prevent excessive memory usage.

Type: number

Default value: 1048576

`expectedContentTypes`¶

List of accepted content types. Defaults to accepting any type if not specified.

Type: array

`readIdleTimeout`¶

Read idle timeout. Closes the connection if no inbound data is received.

Type: object

Default value: PT1M

`exceptionHandler`¶

Custom exception handler enabling interception of all errors related to this source.

Type: object

`ssl`¶

Secure transport configuration. Type: object

Fields of ssl:

`ssl.trustStoreFile`¶

Truststore file or trusted CA certificate; supported formats include JKS, PKCS#12, or PEM. Type: string

`ssl.trustStorePassword`¶

Truststore password. Type: string

`ssl.keyStoreFile`¶

Keystore file; supported formats include JKS, PKCS#12, or PEM Type: string

`ssl.keyStorePassword`¶

Keystore password. Type: string

`ssl.keyPassword`¶

Private key password. Optional — if not set, the key store password will be used. Type: string

`ssl.insecure`¶

If set to true, disables SSL certificate and hostname validation. Intended for debugging purposes only. Doesn't work with mTLS.

Type: boolean

`ssl.hostnameVerifier`¶

Custom hostname verifier for SSL connections. If not specified and 'insecure' is true, hostname verification will be disabled.

Type: object

`socketOptions`¶

Configures operating system options to be applied to the server socket. Supported values are: - SO_SNDBUF, - SO_RCVBUF, - SO_TIMEOUT, - SO_KEEPALIVE, - SO_LINGER, - SO_BACKLOG, - TCP_NODELAY.

Type: object

JSON Schema¶

You can validate or explore the configuration using its JSON Schema.

Usage Examples¶

JAVA

 stream
        .withName("Read data from HTTP server and print to stdout")
        .consumeFromSource(
            HttpSourceConfigBuilder.builder()
                .withDecoder(Decoders.toCharSequenceDecoder())
                .withAddress(HostAndPort.fromParts("0.0.0.0", 8080))
                .withPath("/basket")
                .withExpectedContentTypes("application/json", "text/plain")
                .withHeaders("Content-Type", "CustomHeader")
                .withReadIdleTimeout(Duration.ofMillis(1))
        )
        .terminateWithSink(Sinks.stdout());

Metrics¶

Http metrics¶

Metric enum: org.voltdb.stream.plugin.http.HttpMetric

Prometheus name	Type	Description
`voltsp_http_buffer_capacity_total`	`gauge`	Remaining HTTP source message buffer capacity.
`voltsp_http_connection_attempt_total`	`counter`	Number of HTTP sink connection attempts.
`voltsp_http_connection_error_total`	`counter`	Number of HTTP sink connection errors.
`voltsp_http_connection_timeout_total`	`counter`	Number of HTTP sink connection timeouts.
`voltsp_http_exceeded_payload_size_total`	`counter`	Number of HTTP requests rejected for exceeding the configured payload size.
`voltsp_http_idle_timeout_total`	`counter`	Number of HTTP idle connection timeouts.
`voltsp_http_internal_errors_total`	`counter`	Number of HTTP source internal errors.
`voltsp_http_invalid_media_type_total`	`counter`	Number of HTTP requests rejected for invalid media type.
`voltsp_http_invalid_path_total`	`counter`	Number of HTTP requests rejected for invalid path.
`voltsp_http_invalid_request_method_total`	`counter`	Number of HTTP requests rejected for invalid method.
`voltsp_http_received_bytes`	`counter`	Number of HTTP request body bytes received by the source.
`voltsp_http_received_requests_total`	`counter`	Number of HTTP requests received by the source.
`voltsp_http_request_acknowledged_total`	`counter`	Number of HTTP sink requests acknowledged.
`voltsp_http_request_failed_total`	`counter`	Number of failed HTTP sink requests.
`voltsp_http_response_code_2xx_total`	`counter`	Number of HTTP sink responses with a 2xx status code.
`voltsp_http_response_code_3xx_total`	`counter`	Number of HTTP sink responses with a 3xx status code.
`voltsp_http_response_code_4xx_total`	`counter`	Number of HTTP sink responses with a 4xx status code.
`voltsp_http_response_code_5xx_total`	`counter`	Number of HTTP sink responses with a 5xx status code.
`voltsp_http_request_round_trip_time_seconds`	`histogram`	HTTP sink request round-trip duration.

Http¶

Java dependency management¶

Properties¶

address¶

address.host¶

address.port¶

address.hasBracketlessColons¶

decoder¶

path¶

headers¶

maxContentSize¶

expectedContentTypes¶

readIdleTimeout¶

exceptionHandler¶

ssl¶

ssl.trustStoreFile¶

ssl.trustStorePassword¶

ssl.keyStoreFile¶

ssl.keyStorePassword¶

ssl.keyPassword¶

ssl.insecure¶

ssl.hostnameVerifier¶

socketOptions¶

JSON Schema¶

Usage Examples¶

Metrics¶

Http metrics¶

`address`¶

`address.host`¶

`address.port`¶

`address.hasBracketlessColons`¶

`decoder`¶

`path`¶

`headers`¶

`maxContentSize`¶

`expectedContentTypes`¶

`readIdleTimeout`¶

`exceptionHandler`¶

`ssl`¶

`ssl.trustStoreFile`¶

`ssl.trustStorePassword`¶

`ssl.keyStoreFile`¶

`ssl.keyStorePassword`¶

`ssl.keyPassword`¶

`ssl.insecure`¶

`ssl.hostnameVerifier`¶

`socketOptions`¶