Documentation
¶
Overview ¶
Package connectorruntime executes an automation connector's action NATIVELY in-process — no Node. A connector authored against the ActivePieces framework (@activepieces/pieces-framework + pieces-common) is compiled once to a single CommonJS program (see Bundle) and run inside goja, with the framework supplied by an in-process shim (shim.js) whose only impure primitive is a Go HTTP doer. Because that doer resolves synchronously, an action's `async run(ctx)` settles inside goja's own microtask drain, so a connector executes as ordinary in-process work — a goroutine, not a service.
This is the substrate that retires the standalone ActivePieces Node engine (the `auto` pod). It sits ALONGSIDE apps/automations' Tier-A native Go connectors: those are hand-written Go; this runs the long tail of JS connectors unchanged. Both are org-scoped by the caller — the runtime never resolves a credential itself; it receives the already-resolved `auth`.
Index ¶
- func Bundle(entryPoint string, extraExternal ...string) ([]byte, error)
- func Connectors() []string
- func Has(connector string) bool
- func Mount(app cloud.Router, deps cloud.Deps) error
- func Run(ctx context.Context, org, connector, action string, auth any, ...) (any, error)
- type Connector
- type HTTPDoer
- type HTTPRequest
- type HTTPResponse
- type RunInput
- type Runtime
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bundle ¶
Bundle compiles ONE ActivePieces connector's TypeScript source tree into a single CommonJS program, with the framework packages left external so they resolve to the in-process shim at run time. This is the connector-ingest build step: run it once per connector (offline / CI), commit the JS blob, and the runtime compiles+executes that blob natively in goja — no Node.
entryPoint is the connector's index.ts. extraExternal lets a heavier connector mark additional npm deps external (each then needs a shim); for the framework-only pieces (the long tail) apExternals alone suffice.
func Connectors ¶
func Connectors() []string
Connectors lists the registered connector ids (stable order) for the catalogue / health surface.
func Has ¶
Has reports whether a connector is registered (used to fail closed before a doomed call).
func Mount ¶
Mount wires the native single-connector execution surface onto the cloud binary, per HIP-0126 / HIP-0106:
✓ POST /v1/automations/connectors/:id/run run one connector action in-process
This is the native replacement for the standalone ActivePieces Node engine's /v1/auto/pieces/{piece}/run — same {action,auth,props} -> {ok,output,error} contract, executed in goja in-process (no `auto` pod). It is org-gated: only a validated principal may run a connector, and the caller's resolved credential travels in the request `auth`. The route is DISTINCT from automations' GET /v1/automations/connectors (the catalogue), so the two subsystems compose without collision. It is a TYPED op — one registry entry from which the REST route, the OpenAPI operation, the MCP tool, the CLI command and every generated SDK method follow.
func Run ¶
func Run(ctx context.Context, org, connector, action string, auth any, props map[string]any) (any, error)
Run executes one connector action natively in-process. org is the caller's already-validated tenant — recorded for attribution; the runtime resolves no credential itself, it runs with the auth the caller passes (the KB path hands it this org's KMS-sealed OAuth token). Returns the action result or an error (unknown connector/action, or the action's own failure).
Types ¶
type Connector ¶
type Connector struct {
Name string
// contains filtered or unexported fields
}
Connector is one compiled connector program (an ActivePieces piece bundle wrapped as a CommonJS module). Compile once, Run many times.
type HTTPDoer ¶
type HTTPDoer func(ctx context.Context, req HTTPRequest) (HTTPResponse, error)
HTTPDoer performs one connector HTTP call. ctx bounds it (the caller's request/flow context); the default doer is net/http (see http.go). Injecting a doer lets the host enforce SSRF policy or record egress.
type HTTPRequest ¶
type HTTPRequest struct {
Method string
URL string
Headers map[string]string
QueryParams map[string]string
Body any
TimeoutMS int
}
HTTPRequest is the request an in-VM httpClient.sendRequest hands to the Go doer. It mirrors the ActivePieces HttpRequest fields connectors actually set.
type HTTPResponse ¶
HTTPResponse is what the doer returns; Body is the parsed value (JSON decoded when the response is JSON, else the raw string) the connector sees as response.body.
type RunInput ¶
type RunInput struct {
Action string // action name, e.g. "web_search" / "custom_api_call"
Auth any // resolved credential value handed to ctx.auth
Props map[string]any // ctx.propsValue
}
RunInput is one action invocation.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime holds the compiled shim shared across all connectors and the HTTP doer. It is immutable after construction and safe for concurrent use — each Run builds its own goja VM, so no connector state crosses invocations (the tenant-isolation property: org A's run shares no heap with org B's).
func NewRuntime ¶
NewRuntime compiles the shim and returns a runtime. A nil doer selects the default net/http doer.
func (*Runtime) Compile ¶
Compile wraps a connector's bundled CommonJS source as a callable module and compiles it. bundledJS is the output of Bundle (framework packages external).
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
bundlecmd
command
Command bundlecmd is the offline connector-ingest step: it esbuild-bundles ONE ActivePieces connector source tree (its index.ts) into a single CommonJS program with the framework packages left external, and writes the blob.
|
Command bundlecmd is the offline connector-ingest step: it esbuild-bundles ONE ActivePieces connector source tree (its index.ts) into a single CommonJS program with the framework packages left external, and writes the blob. |