Package io.roastedroot.proxywasm

Class PluginFactory.Builder

  • Enclosing interface:
    PluginFactory
    public static final class PluginFactory.Builder
extends Object
    Builder for creating a PluginFactory instance that can create Plugin instances with pre-configured settings.

    • Method Detail

      • withName

        public PluginFactory.Builder withName​(String name)
        Sets the optional name for this plugin instance. This name can be used for identification and logging purposes.
        Parameters:
        name - the desired name for the plugin.
        Returns:
        this Builder instance for method chaining.

      • withForeignFunctions

        public PluginFactory.Builder withForeignFunctions​(Map<String,​ForeignFunction> functions)
        Registers foreign (host-provided) functions that can be called by the WASM plugin. These functions allow the plugin to interact with the host environment beyond the standard Proxy-WASM ABI calls.
        Parameters:
        functions - A map where keys are the function names expected by the WASM module, and values are ForeignFunction implementations provided by the host.
        Returns:
        this Builder instance for method chaining.
        See Also:
        ForeignFunction

      • withUpstreams

        public PluginFactory.Builder withUpstreams​(Map<String,​URI> upstreams)
        Defines mappings from logical upstream names (used within the plugin) to actual network URIs. This allows the plugin to make network calls (e.g., HTTP, gRPC) to services known by name, without needing to hardcode addresses.
        Parameters:
        upstreams - A map where keys are the logical upstream names used by the plugin, and values are the corresponding URIs of the target services.
        Returns:
        this Builder instance for method chaining.

      • withStrictUpstreams

        public PluginFactory.Builder withStrictUpstreams​(boolean strictUpstreams)
        Configures the behavior when a plugin attempts to call an upstream that is not defined in the `upstreams` map provided via withUpstreams(Map).

        If strictUpstreams is true, attempting to use an undefined upstream name will result in an error being reported back to the plugin.

        If strictUpstreams is false (the default behavior if this method is not called), the host will try to parse the upstream name as URI.

        Parameters:
        strictUpstreams - true to enforce that all used upstream names must be explicitly mapped, false to allow fallback resolution.
        Returns:
        this Builder instance for method chaining.

      • withMinTickPeriodMilliseconds

        public PluginFactory.Builder withMinTickPeriodMilliseconds​(int minTickPeriodMilliseconds)
        Sets a minimum interval for the plugin's periodic timer ticks (proxy_on_tick). The Proxy-WASM ABI allows plugins to request a timer tick period. This setting enforces a lower bound on that period to prevent plugins from requesting excessively frequent ticks, which could overload the host.

        If the plugin requests a tick period shorter than this minimum, the host will use this minimum value instead.

        Parameters:
        minTickPeriodMilliseconds - the minimum allowed tick period in milliseconds. A value of 0 or less implies no minimum enforcement (host default behavior).
        Returns:
        this Builder instance for method chaining.

      • withLogger

        public PluginFactory.Builder withLogger​(LogHandler logger)
        Provides a LogHandler implementation for the plugin to use. This handler receives log messages generated by the WASM module via the proxy_log ABI call. If no logger is provided, LogHandler.DEFAULT (a no-op logger) is used.
        Parameters:
        logger - the LogHandler implementation to handle plugin logs.
        Returns:
        this Builder instance for method chaining.
        See Also:
        LogHandler

      • withMetricsHandler

        public PluginFactory.Builder withMetricsHandler​(MetricsHandler metricsHandler)
        Provides a MetricsHandler implementation for the plugin to use. This handler manages metric definition, recording, and retrieval requested by the WASM module via the relevant proxy_* ABI calls (e.g., proxy_define_metric). If no handler is provided, MetricsHandler.DEFAULT (which returns UNIMPLEMENTED) might be used implicitly.
        Parameters:
        metricsHandler - the MetricsHandler implementation to manage plugin metrics.
        Returns:
        this Builder instance for method chaining.
        See Also:
        MetricsHandler

      • withSharedQueueHandler

        public PluginFactory.Builder withSharedQueueHandler​(SharedQueueHandler sharedQueueHandler)
        Provides a SharedQueueHandler implementation for the plugin to use. This handler manages operations on shared message queues requested by the WASM module via the relevant proxy_* ABI calls (e.g., proxy_register_shared_queue). If no handler is provided, SharedQueueHandler.DEFAULT (which returns UNIMPLEMENTED) might be used implicitly.
        Parameters:
        sharedQueueHandler - the SharedQueueHandler implementation to manage shared queues.
        Returns:
        this Builder instance for method chaining.
        See Also:
        SharedQueueHandler

      • withSharedDataHandler

        public PluginFactory.Builder withSharedDataHandler​(SharedDataHandler sharedDataHandler)
        Provides a SharedDataHandler implementation for the plugin to use. This handler manages operations on shared key-value data requested by the WASM module via the relevant proxy_* ABI calls (e.g., proxy_get_shared_data). If no handler is provided, SharedDataHandler.DEFAULT (which returns UNIMPLEMENTED) might be used implicitly.
        Parameters:
        sharedDataHandler - the SharedDataHandler implementation to manage shared data.
        Returns:
        this Builder instance for method chaining.
        See Also:
        SharedDataHandler

      • withVmConfig

        public PluginFactory.Builder withVmConfig​(byte[] vmConfig)
        Sets the Virtual Machine (VM) configuration data for the plugin. This configuration is typically provided once when the VM (and the plugin) is initialized. It's accessible to the plugin via the proxy_get_vm_configuration ABI call.
        Parameters:
        vmConfig - A byte array containing the VM configuration data.
        Returns:
        this Builder instance for method chaining.

      • withVmConfig

        public PluginFactory.Builder withVmConfig​(String vmConfig)
        Sets the Virtual Machine (VM) configuration data for the plugin using a String. The string will be converted to bytes using the platform's default charset. This configuration is accessible via the proxy_get_vm_configuration ABI call.
        Parameters:
        vmConfig - A String containing the VM configuration data.
        Returns:
        this Builder instance for method chaining.
        See Also:
        withVmConfig(byte[])

      • withPluginConfig

        public PluginFactory.Builder withPluginConfig​(byte[] pluginConfig)
        Sets the specific configuration data for this plugin instance. This configuration is provided during the plugin's initialization phase (via proxy_on_configure) and allows tailoring the plugin's behavior. It's accessible to the plugin via the proxy_get_plugin_configuration ABI call.
        Parameters:
        pluginConfig - A byte array containing the plugin-specific configuration data.
        Returns:
        this Builder instance for method chaining.

      • withPluginConfig

        public PluginFactory.Builder withPluginConfig​(String pluginConfig)
        Sets the specific configuration data for this plugin instance using a String. The string will be converted to bytes using the platform's default charset. This configuration is accessible via the proxy_get_plugin_configuration ABI call.
        Parameters:
        pluginConfig - A String containing the plugin-specific configuration data.
        Returns:
        this Builder instance for method chaining.
        See Also:
        withPluginConfig(byte[])

      • withImportMemory

        public PluginFactory.Builder withImportMemory​(ImportMemory memory)
        Provides an explicit memory instance to be used by the WASM module.
        Parameters:
        memory - The ImportMemory instance to be used by the WASM module.
        Returns:
        this Builder instance for method chaining.

      • withMachineFactory

        public PluginFactory.Builder withMachineFactory​(Function<Instance,​Machine> machineFactory)
        Configures a custom factory for creating the Machine used to execute the WASM code. The Machine controls the low-level execution of WASM instructions. By default, an interpreter-based machine is used. Providing a custom factory allows using alternative execution strategies, such as wasm to bytecode compilation to improve execution performance.

        See the Chicory documentation (https://chicory.dev/docs/usage/runtime-compiler) for more details on WASM to bytecode compilation and execution.

        Parameters:
        machineFactory - A function that takes a WASM Instance and returns a Machine.
        Returns:
        this Builder instance for method chaining.

      • withWasiOptions

        public PluginFactory.Builder withWasiOptions​(com.dylibso.chicory.wasi.WasiOptions options)
        Configures WebAssembly System Interface (WASI) options for the plugin instance. WASI provides a standard interface for WASM modules to interact with the underlying operating system for tasks like file system access, environment variables, etc. While Proxy-WASM defines its own ABI, some modules might also utilize WASI features.
        Parameters:
        options - The WasiOptions to configure for the WASI environment.
        Returns:
        this Builder instance for method chaining.

      • withShared

        public PluginFactory.Builder withShared​(boolean shared)
        Configures whether the plugin instance should be shared across multiple host requests or contexts.

        If shared is true, a single WASM instance will be created and reused. across multiple concurrent requests. Since Proxy-Wasm plugins are not thread-safe, the requests will contend on an access lock for the plugin. Using a shared plugin allows the plugin to maintain state between the requests. It will use less memory but will have a performance impact due to the contention.

        If shared is false (the default), the host will create a new, separate WASM instance for each request or context (depending on the host implementation and threading model). This provides better isolation, eliminates contention, but consumes more memory.

        Parameters:
        shared - true to indicate the plugin instance can be shared, false otherwise.
        Returns:
        this Builder instance for method chaining.

      • build

        public PluginFactory build()
        Constructs a PluginFactory instance that will create Plugin instances using the configuration provided to this builder.
        Returns:
        A PluginFactory that creates plugins with the specified configuration.