Proxy Function & Remote Invocation

This chapter introduces the proxy function mechanism in FrameX, including a new decorator, runtime support, and an HTTP endpoint for remote proxy invocation.

This feature enables cross-FrameX-instance function execution, allowing plugins to transparently call functions hosted on remote FrameX instances.

1) Background & Motivation

In multi-FrameX deployments, different instances may run under different security or infrastructure constraints.

Typical scenarios include:

  • Instance A does not have access to MySQL
  • Instance A is restricted to HTTP-only outbound access
  • Instance B has database access or privileged network permissions

To fully implement plugin functionality without violating security constraints, FrameX introduces the on_proxy mechanism, enabling remote function proxying across FrameX instances.

2) Design Overview

  • Functions can be marked as proxy-enabled
  • FrameX automatically decides whether to execute locally or remotely
  • No explicit client/server role configuration is required
  • The same code runs on both sides

3) Defining a Proxy Function

Step 1: Register Proxy Function in Plugin

Proxy functions must be registered during plugin startup.

Important: Lazy import is required.

@on_register()
class ExamplePlugin(BasePlugin):
    def __init__(self, **kwargs: Any) -> None:
        super().__init__(**kwargs)

    async def on_start(self) -> None:
        from demo.some import example_func  # Important: Lazy import

        await register_proxy_func(example_func)

Step 2: Mark Function with on_proxy

@on_proxy()
@other_func
async def example_func(id, user):
    data = "..."
    return data

4) Enabling Remote Proxy Invocation

To enable remote execution, add the following configuration to config.toml.

Proxy Configuration

[plugins.proxy]
proxy_urls = ["http://remotehost:8080"]
white_list = ["/api/v1/proxy/remote"]
proxy_functions = {"http://remotehost:8080" = ["demo.some.example_func"]}

Authentication Configuration

[plugins.proxy.auth]
rules = {"/api/v1/proxy/remote" = ["proxy-key"],"/api/v1/openapi.json" = ["openapi-key"]}

Once configured, FrameX automatically routes function calls to remote instances when required.

5) Security, Performance & Compatibility

Security

  • Automatic serialization and deserialization
  • Data compression and encryption
  • Safe fallback when local decorators fail

Compatibility

Supports:

  • Primitive types
  • BaseModel (Pydantic)
  • Most stateless class objects