Class NativeHttpBindings

java.lang.Object
ai.tegmentum.wasmtime4j.panama.NativeHttpBindings
public final class NativeHttpBindings extends Object
Native function bindings for WASI HTTP operations.

Provides type-safe wrappers for all WASI HTTP native functions including config builder operations, config management, HTTP context lifecycle, statistics collection, and linker integration.

  • Method Details

    • getInstance

      public static NativeHttpBindings getInstance()
      Gets the singleton instance.
      Returns:
      the singleton instance
      Throws:
      RuntimeException - if initialization fails

    • wasiHttpConfigBuilderNew

      public MemorySegment wasiHttpConfigBuilderNew()
      Creates a new WASI HTTP config builder.
      Returns:
      pointer to the config builder, or null on failure

    • wasiHttpConfigBuilderAllowHost

      public int wasiHttpConfigBuilderAllowHost(MemorySegment builderPtr, MemorySegment hostPtr)
      Adds an allowed host to the config builder.
      Parameters:
      builderPtr - pointer to the config builder
      hostPtr - pointer to the host string
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderBlockHost

      public int wasiHttpConfigBuilderBlockHost(MemorySegment builderPtr, MemorySegment hostPtr)
      Adds a blocked host to the config builder.
      Parameters:
      builderPtr - pointer to the config builder
      hostPtr - pointer to the host string
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderAllowAllHosts

      public int wasiHttpConfigBuilderAllowAllHosts(MemorySegment builderPtr, boolean allow)
      Sets whether all hosts are allowed.
      Parameters:
      builderPtr - pointer to the config builder
      allow - true to allow all hosts
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetConnectTimeout

      public int wasiHttpConfigBuilderSetConnectTimeout(MemorySegment builderPtr, long timeoutMs)
      Sets the connect timeout in milliseconds.
      Parameters:
      builderPtr - pointer to the config builder
      timeoutMs - timeout in milliseconds
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetReadTimeout

      public int wasiHttpConfigBuilderSetReadTimeout(MemorySegment builderPtr, long timeoutMs)
      Sets the read timeout in milliseconds.
      Parameters:
      builderPtr - pointer to the config builder
      timeoutMs - timeout in milliseconds
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetWriteTimeout

      public int wasiHttpConfigBuilderSetWriteTimeout(MemorySegment builderPtr, long timeoutMs)
      Sets the write timeout in milliseconds.
      Parameters:
      builderPtr - pointer to the config builder
      timeoutMs - timeout in milliseconds
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetMaxConnections

      public int wasiHttpConfigBuilderSetMaxConnections(MemorySegment builderPtr, int maxConnections)
      Sets the maximum number of connections.
      Parameters:
      builderPtr - pointer to the config builder
      maxConnections - maximum connections
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetMaxConnectionsPerHost

      public int wasiHttpConfigBuilderSetMaxConnectionsPerHost(MemorySegment builderPtr, int maxConnectionsPerHost)
      Sets the maximum connections per host.
      Parameters:
      builderPtr - pointer to the config builder
      maxConnectionsPerHost - maximum connections per host
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetMaxRequestBodySize

      public int wasiHttpConfigBuilderSetMaxRequestBodySize(MemorySegment builderPtr, long maxSize)
      Sets the maximum request body size.
      Parameters:
      builderPtr - pointer to the config builder
      maxSize - maximum size in bytes
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetMaxResponseBodySize

      public int wasiHttpConfigBuilderSetMaxResponseBodySize(MemorySegment builderPtr, long maxSize)
      Sets the maximum response body size.
      Parameters:
      builderPtr - pointer to the config builder
      maxSize - maximum size in bytes
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetHttpsRequired

      public int wasiHttpConfigBuilderSetHttpsRequired(MemorySegment builderPtr, boolean required)
      Sets whether HTTPS is required.
      Parameters:
      builderPtr - pointer to the config builder
      required - true to require HTTPS
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetCertificateValidation

      public int wasiHttpConfigBuilderSetCertificateValidation(MemorySegment builderPtr, boolean enabled)
      Sets whether certificate validation is enabled.
      Parameters:
      builderPtr - pointer to the config builder
      enabled - true to enable certificate validation
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetHttp2Enabled

      public int wasiHttpConfigBuilderSetHttp2Enabled(MemorySegment builderPtr, boolean enabled)
      Sets whether HTTP/2 is enabled.
      Parameters:
      builderPtr - pointer to the config builder
      enabled - true to enable HTTP/2
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetConnectionPooling

      public int wasiHttpConfigBuilderSetConnectionPooling(MemorySegment builderPtr, boolean enabled)
      Sets whether connection pooling is enabled.
      Parameters:
      builderPtr - pointer to the config builder
      enabled - true to enable connection pooling
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetFollowRedirects

      public int wasiHttpConfigBuilderSetFollowRedirects(MemorySegment builderPtr, boolean follow)
      Sets whether to follow redirects.
      Parameters:
      builderPtr - pointer to the config builder
      follow - true to follow redirects
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetMaxRedirects

      public int wasiHttpConfigBuilderSetMaxRedirects(MemorySegment builderPtr, int maxRedirects)
      Sets the maximum number of redirects to follow.
      Parameters:
      builderPtr - pointer to the config builder
      maxRedirects - maximum redirects
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderSetUserAgent

      public int wasiHttpConfigBuilderSetUserAgent(MemorySegment builderPtr, MemorySegment userAgentPtr)
      Sets the user agent string.
      Parameters:
      builderPtr - pointer to the config builder
      userAgentPtr - pointer to the user agent string
      Returns:
      0 on success, negative error code on failure

    • wasiHttpConfigBuilderBuild

      public MemorySegment wasiHttpConfigBuilderBuild(MemorySegment builderPtr)
      Builds a WASI HTTP config from the builder.
      Parameters:
      builderPtr - pointer to the config builder
      Returns:
      pointer to the config, or null on failure

    • wasiHttpConfigBuilderFree

      public void wasiHttpConfigBuilderFree(MemorySegment builderPtr)
      Frees a WASI HTTP config builder.
      Parameters:
      builderPtr - pointer to the config builder

    • wasiHttpConfigDefault

      public MemorySegment wasiHttpConfigDefault()
      Creates a default WASI HTTP config.
      Returns:
      pointer to the config, or null on failure

    • wasiHttpConfigFree

      public void wasiHttpConfigFree(MemorySegment configPtr)
      Frees a WASI HTTP config.
      Parameters:
      configPtr - pointer to the config

    • wasiHttpContextNew

      public MemorySegment wasiHttpContextNew(MemorySegment configPtr)
      Creates a new WASI HTTP context with the specified config.
      Parameters:
      configPtr - pointer to the config
      Returns:
      pointer to the context, or null on failure

    • wasiHttpContextNewDefault

      public MemorySegment wasiHttpContextNewDefault()
      Creates a new WASI HTTP context with default config.
      Returns:
      pointer to the context, or null on failure

    • wasiHttpContextGetId

      public long wasiHttpContextGetId(MemorySegment contextPtr)
      Gets the ID of a WASI HTTP context.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      the context ID

    • wasiHttpContextIsValid

      public int wasiHttpContextIsValid(MemorySegment contextPtr)
      Checks if a WASI HTTP context is valid.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      1 if valid, 0 otherwise

    • wasiHttpContextIsHostAllowed

      public int wasiHttpContextIsHostAllowed(MemorySegment contextPtr, MemorySegment hostPtr)
      Checks if a host is allowed by the context.
      Parameters:
      contextPtr - pointer to the context
      hostPtr - pointer to the host string
      Returns:
      1 if allowed, 0 otherwise

    • wasiHttpContextResetStats

      public int wasiHttpContextResetStats(MemorySegment contextPtr)
      Resets the statistics for a WASI HTTP context.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      0 on success, negative error code on failure

    • wasiHttpContextStatsTotalRequests

      public long wasiHttpContextStatsTotalRequests(MemorySegment contextPtr)
      Gets the total number of requests.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      total request count

    • wasiHttpContextStatsSuccessfulRequests

      public long wasiHttpContextStatsSuccessfulRequests(MemorySegment contextPtr)
      Gets the number of successful requests.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      successful request count

    • wasiHttpContextStatsFailedRequests

      public long wasiHttpContextStatsFailedRequests(MemorySegment contextPtr)
      Gets the number of failed requests.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      failed request count

    • wasiHttpContextStatsActiveRequests

      public int wasiHttpContextStatsActiveRequests(MemorySegment contextPtr)
      Gets the number of active requests.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      active request count

    • wasiHttpContextStatsBytesSent

      public long wasiHttpContextStatsBytesSent(MemorySegment contextPtr)
      Gets the total bytes sent.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      total bytes sent

    • wasiHttpContextStatsBytesReceived

      public long wasiHttpContextStatsBytesReceived(MemorySegment contextPtr)
      Gets the total bytes received.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      total bytes received

    • wasiHttpContextStatsConnectionTimeouts

      public long wasiHttpContextStatsConnectionTimeouts(MemorySegment contextPtr)
      Gets the number of connection timeouts.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      connection timeout count

    • wasiHttpContextStatsReadTimeouts

      public long wasiHttpContextStatsReadTimeouts(MemorySegment contextPtr)
      Gets the number of read timeouts.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      read timeout count

    • wasiHttpContextStatsBlockedRequests

      public long wasiHttpContextStatsBlockedRequests(MemorySegment contextPtr)
      Gets the number of blocked requests.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      blocked request count

    • wasiHttpContextStatsBodySizeViolations

      public long wasiHttpContextStatsBodySizeViolations(MemorySegment contextPtr)
      Gets the number of body size violations.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      body size violation count

    • wasiHttpContextStatsActiveConnections

      public int wasiHttpContextStatsActiveConnections(MemorySegment contextPtr)
      Gets the number of active connections.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      active connection count

    • wasiHttpContextStatsIdleConnections

      public int wasiHttpContextStatsIdleConnections(MemorySegment contextPtr)
      Gets the number of idle connections.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      idle connection count

    • wasiHttpContextStatsAvgDurationMs

      public long wasiHttpContextStatsAvgDurationMs(MemorySegment contextPtr)
      Gets the average request duration in milliseconds.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      average duration in milliseconds

    • wasiHttpContextStatsMinDurationMs

      public long wasiHttpContextStatsMinDurationMs(MemorySegment contextPtr)
      Gets the minimum request duration in milliseconds.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      minimum duration in milliseconds

    • wasiHttpContextStatsMaxDurationMs

      public long wasiHttpContextStatsMaxDurationMs(MemorySegment contextPtr)
      Gets the maximum request duration in milliseconds.
      Parameters:
      contextPtr - pointer to the context
      Returns:
      maximum duration in milliseconds

    • wasiHttpContextFree

      public void wasiHttpContextFree(MemorySegment contextPtr)
      Frees a WASI HTTP context.
      Parameters:
      contextPtr - pointer to the context

    • wasiHttpIsAvailable

      public int wasiHttpIsAvailable()
      Checks if WASI HTTP support is available.
      Returns:
      1 if WASI HTTP is available, 0 otherwise

    • markInitialized

      protected void markInitialized()
      Marks this binding set as initialized. Subclasses should call this after registering all function bindings and initializing hot-path MethodHandles.

    • isInitialized

      public boolean isInitialized()
      Checks if the bindings are initialized and available.
      Returns:
      true if initialized, false otherwise

    • addFunctionBinding

      protected void addFunctionBinding(String functionName, FunctionDescriptor descriptor)
      Registers a native function binding with a given descriptor.
      Parameters:
      functionName - the native function symbol name
      descriptor - the Panama FunctionDescriptor for the native function

    • getFunctionBinding

      protected ai.tegmentum.wasmtime4j.panama.NativeBindingsBase.FunctionBinding getFunctionBinding(String functionName)
      Gets a registered function binding by name.
      Parameters:
      functionName - the native function symbol name
      Returns:
      the function binding, or null if not registered

    • callNativeFunction

      public <T> T callNativeFunction(String functionName, Class<T> returnType, Object... args)
      Calls a native function with type safety.
      Parameters:
      functionName - the name of the function
      returnType - the expected return type
      args - the function arguments
      Returns:
      the function result
      Throws:
      IllegalStateException - if the function call fails

    • validatePointer

      protected void validatePointer(MemorySegment pointer, String name)
      Validates that a pointer is not null.
      Parameters:
      pointer - the pointer to validate
      name - the name of the parameter for error messages
      Throws:
      IllegalArgumentException - if the pointer is null

    • validateSize

      protected void validateSize(long size, String name)
      Validates that a size is positive.
      Parameters:
      size - the size to validate
      name - the name of the parameter for error messages
      Throws:
      IllegalArgumentException - if the size is not positive

    • extractValueForNative

      protected Object[] extractValueForNative(ai.tegmentum.wasmtime4j.WasmValue value)
      Extracts value components from WasmValue for passing to native code.
      Parameters:
      value - the WasmValue to extract components from
      Returns:
      array containing [i32Value, i64Value, f32Value, f64Value, refValue]