plugin

Overview ¶

Real plugin backend: generate Go source, compile it with `go build -buildmode=plugin`, and load the resulting .so.

Go's plugin package is only implemented on linux/darwin/freebsd and needs cgo, hence the build constraint. Everywhere else (Windows, most notably) backend_stub.go supplies the same four symbols and every entry point fails with an explanation. Keeping the constraint here rather than at the module level is what lets `require("plugin")` resolve on all platforms so scripts can branch on `plugin.supported`.

Package plugin lets a LuaScript program reach into arbitrary Go libraries at run time, in the spirit of Goby's native/plugin.

A script declares which Go packages it wants and which functions to lift out of them. The module generates a small `package main` that re-exports those functions as package-level vars, compiles it with `go build -buildmode=plugin`, opens the resulting shared object, and dispatches calls through reflect:

local plugin = require("plugin")

local p = plugin.generate("strutil", {
  packages  = { { name = "strings" } },
  functions = { { pkg = "strings", name = "ToUpper" } },
})

print(p:call("ToUpper", "hello"))  --> HELLO
print(p.ToUpper("hello"))          --> HELLO  (same call, via __index)

Go values with no Lua counterpart — a *sql.DB, say — come back as GoValue objects whose exported methods and fields stay reachable (see convert.go), so the database/sql idiom Goby demonstrates works here too:

local p = plugin.generate("db", {
  packages  = { { name = "database/sql" }, { prefix = "_", name = "github.com/lib/pq" } },
  functions = { { pkg = "sql", name = "Open" } },
})
local db, err = p.Open("postgres", "...")
local rows    = db:Query("select 1")

Platform support ¶

Go's plugin package only exists on linux, darwin and freebsd, and only with cgo. On Windows there is no dynamic loading to be had — plugin.Open returns "plugin: not implemented" — so this module still loads (require succeeds) but generate/open raise an error naming the platform. Scripts that want to stay portable should branch on `plugin.supported` first.

Security ¶

generate() runs the Go compiler and then loads native code into this process. That is arbitrary code execution by construction — the same bargain Goby makes, and the whole point of the feature. Do not hand a spec built from untrusted input to this module.