refactor(web): start Go ABI rewrite of plugins/web (W-G0)

Archive the Rust web plugin and add a Go c-shared skeleton with ABI v2
bridge, build script, design doc/ADR, and smoke test so multi-language
plugins and full web parity can proceed wave by wave.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-10 14:47:43 +08:00
1 parent fb6254e501
commit ca40c698a2
42 files changed
+955 -3

No files matched your search

File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
+23
View File
@@ -0,0 +1,23 @@
# Marqdo `plugins/web` — Go (C ABI v2)
施工图:[doc/design/ext-web-go-rewrite.md](../../doc/design/ext-web-go-rewrite.md) · ADR:[0004](../../doc/adr/0004-web-plugin-go.md)
## Build
```bash
./scripts/build-web-plugin.sh
# → plugins/web/build/libweb.so (also copied to target/debug|release)
export MARQDO_WEB_PLUGIN=$PWD/plugins/web/build/libweb.so
```
Requires **Go 1.22+** with cgo (`CGO_ENABLED=1`) and a C toolchain.
## Layout
| Path | Role |
|------|------|
| `plugin.go` | `//export` ABI entry + registration |
| `abi/marqdo_abi.h` | C contract (from `include/`) |
| `internal/*` | page / db / http / ws / … |
迁移期 Rust 参考实现:`plugins/web-rust-archive/`(勿再演进)。
+55
View File
@@ -0,0 +1,55 @@
/* Marqdo plugin ABI v2 — C contract (source of truth).
*
* Plugins are optional shared libraries (.dll / .so / .dylib), never linked
* into the marqdo binary. Values cross the boundary as UTF-8 JSON.
*
* v1: register_fn, alloc, free
* v2: + host_query (allowlisted host introspection for plugins)
*/
#ifndef MARQDO_ABI_H
#define MARQDO_ABI_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define MARQDO_ABI_VERSION 2u
#define MARQDO_ABI_VERSION_MIN 1u
/* Plugin function: args_json is a UTF-8 JSON object whose keys are param names.
* On success: return 0, set *out_json to a heap string (host frees via free).
* On failure: return non-zero; optional *err_msg heap string (host frees).
* out_json / err_msg may be left NULL.
*/
typedef int (*MarqdoPluginFn)(const char *args_json, char **out_json, char **err_msg);
/* Host → plugin query (v2). `name` is an allowlisted query id.
* Same success/failure convention as MarqdoPluginFn.
*/
typedef int (*MarqdoHostQueryFn)(void *userdata, const char *name, const char *args_json,
char **out_json, char **err_msg);
typedef struct MarqdoHostApi {
void *userdata;
/* params: comma-separated param names in order, e.g. "a,b". May be "". */
int (*register_fn)(void *userdata, const char *name, const char *params,
MarqdoPluginFn fn);
void *(*alloc)(size_t n);
void (*free)(void *p);
/* v2: NULL for hosts that only speak v1; required when plugin abi >= 2 */
MarqdoHostQueryFn host_query;
} MarqdoHostApi;
/* Required exports from every plugin shared library. */
uint32_t marqdo_plugin_abi_version(void);
int marqdo_plugin_init(const MarqdoHostApi *host);
void marqdo_plugin_shutdown(void);
#ifdef __cplusplus
}
#endif
#endif /* MARQDO_ABI_H */
+40
View File
@@ -0,0 +1,40 @@
/* Go/cgo local ABI view — same layout as include/marqdo_abi.h.
* cgo //export cannot emit `const` on parameters; this header matches
* the generated prototypes so -buildmode=c-shared links cleanly.
* Wire format & semantics remain ABI v2 (see include/marqdo_abi.h).
*/
#ifndef MARQDO_ABI_CGO_H
#define MARQDO_ABI_CGO_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define MARQDO_ABI_VERSION 2u
#define MARQDO_ABI_VERSION_MIN 1u
typedef int (*MarqdoPluginFn)(char *args_json, char **out_json, char **err_msg);
typedef int (*MarqdoHostQueryFn)(void *userdata, char *name, char *args_json,
char **out_json, char **err_msg);
typedef struct MarqdoHostApi {
void *userdata;
int (*register_fn)(void *userdata, char *name, char *params, MarqdoPluginFn fn);
void *(*alloc)(size_t n);
void (*free)(void *p);
MarqdoHostQueryFn host_query;
} MarqdoHostApi;
uint32_t marqdo_plugin_abi_version(void);
int marqdo_plugin_init(MarqdoHostApi *host);
void marqdo_plugin_shutdown(void);
#ifdef __cplusplus
}
#endif
#endif /* MARQDO_ABI_CGO_H */
+3
View File
@@ -0,0 +1,3 @@
module github.com/marqdo/marqdo/plugins/web
go 1.24.5
+51
View File
@@ -0,0 +1,51 @@
package page
import "strconv"
// New builds a page bag (ABI web_page_new), matching the Rust plugin shape.
func New(args map[string]any) map[string]any {
title := strOpt(args, "title", "Marqdo Web")
intro := strOpt(args, "intro", "")
out := map[string]any{
"title": title,
"intro": intro,
}
if s, ok := strAny(args, "shell_css", "壳样式"); ok {
out["shell_css"] = s
}
if s, ok := strAny(args, "layout", "布局"); ok {
out["layout"] = s
}
if s, ok := strAny(args, "asset_version", "资源版本"); ok {
out["asset_version"] = s
}
return out
}
func strOpt(args map[string]any, key, def string) string {
if s, ok := strAny(args, key); ok {
return s
}
return def
}
func strAny(args map[string]any, keys ...string) (string, bool) {
for _, k := range keys {
v, ok := args[k]
if !ok || v == nil {
continue
}
switch t := v.(type) {
case string:
return t, true
case float64:
if t == float64(int64(t)) {
return strconv.FormatInt(int64(t), 10), true
}
return strconv.FormatFloat(t, 'f', -1, 64), true
case bool:
return strconv.FormatBool(t), true
}
}
return "", false
}
+29
View File
@@ -0,0 +1,29 @@
package page_test
import (
"testing"
"github.com/marqdo/marqdo/plugins/web/internal/page"
)
func TestNewDefaults(t *testing.T) {
p := page.New(map[string]any{})
if p["title"] != "Marqdo Web" {
t.Fatalf("title=%v", p["title"])
}
if p["intro"] != "" {
t.Fatalf("intro=%v", p["intro"])
}
}
func TestNewZhAliases(t *testing.T) {
p := page.New(map[string]any{
"title": "T",
"壳样式": "minimal",
"布局": "bare",
"资源版本": "v1",
})
if p["shell_css"] != "minimal" || p["layout"] != "bare" || p["asset_version"] != "v1" {
t.Fatalf("%v", p)
}
}
+28
View File
@@ -0,0 +1,28 @@
package plugin
// HostFns holds callbacks into the Marqdo host (valid after marqdo_plugin_init).
type HostFns struct {
Query func(name, argsJSON string) (string, error)
}
var host HostFns
// SetHost stores host callbacks from ABI init.
func SetHost(h HostFns) { host = h }
// Shutdown clears plugin global state (HTTP servers, pools, …).
func Shutdown() {
host = HostFns{}
}
// Query runs an allowlisted host_query.
func Query(name, argsJSON string) (string, error) {
if host.Query == nil {
return "", errString("host_query not available")
}
return host.Query(name, argsJSON)
}
type errString string
func (e errString) Error() string { return string(e) }
+185
View File
@@ -0,0 +1,185 @@
// Package main builds the Marqdo web plugin as a C shared library (ABI v2).
//
// go build -buildmode=c-shared -o build/libweb.so .
//
// See doc/design/ext-web-go-rewrite.md (W-G0+).
package main
/*
#cgo CFLAGS: -I${SRCDIR}/abi
#include "marqdo_abi_cgo.h"
#include <stdlib.h>
#include <string.h>
static void *g_userdata;
static int (*g_register_fn)(void *, char *, char *, MarqdoPluginFn);
static void *(*g_alloc)(size_t);
static void (*g_free)(void *);
static MarqdoHostQueryFn g_host_query;
static void host_save(MarqdoHostApi *h) {
g_userdata = h->userdata;
g_register_fn = h->register_fn;
g_alloc = h->alloc;
g_free = h->free;
g_host_query = h->host_query;
}
static char *host_strdup(const char *s) {
if (!g_alloc || !s) return NULL;
size_t n = strlen(s);
char *p = (char *)g_alloc(n + 1);
if (!p) return NULL;
memcpy(p, s, n);
p[n] = 0;
return p;
}
static void host_free(void *p) {
if (g_free && p) g_free(p);
}
static int host_register(char *name, char *params, MarqdoPluginFn fn) {
if (!g_register_fn) return 1;
return g_register_fn(g_userdata, name, params, fn);
}
static int host_query(char *name, char *args_json, char **out_json, char **err_msg) {
if (!g_host_query) return 1;
return g_host_query(g_userdata, name, args_json, out_json, err_msg);
}
extern int web_go_ready(char *args_json, char **out_json, char **err_msg);
extern int web_page_new(char *args_json, char **out_json, char **err_msg);
static int register_core(void) {
if (host_register((char *)"web_go_ready", (char *)"", web_go_ready) != 0) return 1;
if (host_register((char *)"web_page_new", (char *)"title,intro,shell_css,layout,asset_version", web_page_new) != 0) return 1;
return 0;
}
*/
import "C"
import (
"encoding/json"
"fmt"
"unsafe"
"github.com/marqdo/marqdo/plugins/web/internal/page"
"github.com/marqdo/marqdo/plugins/web/internal/plugin"
)
func main() {}
//export marqdo_plugin_abi_version
func marqdo_plugin_abi_version() C.uint32_t {
return 2
}
//export marqdo_plugin_init
func marqdo_plugin_init(host *C.MarqdoHostApi) C.int {
if host == nil {
return 1
}
C.host_save(host)
plugin.SetHost(plugin.HostFns{Query: hostQueryJSON})
return C.register_core()
}
//export marqdo_plugin_shutdown
func marqdo_plugin_shutdown() {
plugin.Shutdown()
}
func hostQueryJSON(name, argsJSON string) (string, error) {
cname := C.CString(name)
cargs := C.CString(argsJSON)
defer C.free(unsafe.Pointer(cname))
defer C.free(unsafe.Pointer(cargs))
var out, errMsg *C.char
rc := C.host_query(cname, cargs, &out, &errMsg)
outGo := cstrTakeHost(out)
errGo := cstrTakeHost(errMsg)
if rc != 0 {
if errGo == "" {
errGo = "host_query failed"
}
return "", fmt.Errorf("%s", errGo)
}
if outGo == "" {
outGo = "null"
}
return outGo, nil
}
func cstrTakeHost(p *C.char) string {
if p == nil {
return ""
}
s := C.GoString(p)
C.host_free(unsafe.Pointer(p))
return s
}
func hostDup(s string) *C.char {
cs := C.CString(s)
defer C.free(unsafe.Pointer(cs))
return C.host_strdup(cs)
}
func replyJSON(outJSON **C.char, errMsg **C.char, v any, err error) C.int {
if err != nil {
if errMsg != nil {
*errMsg = hostDup(err.Error())
}
return 1
}
b, e := json.Marshal(v)
if e != nil {
if errMsg != nil {
*errMsg = hostDup(e.Error())
}
return 1
}
if outJSON != nil {
*outJSON = hostDup(string(b))
}
return 0
}
func parseArgs(argsJSON *C.char) (map[string]any, error) {
if argsJSON == nil {
return map[string]any{}, nil
}
s := C.GoString(argsJSON)
if s == "" {
return map[string]any{}, nil
}
var m map[string]any
if err := json.Unmarshal([]byte(s), &m); err != nil {
return nil, err
}
if m == nil {
m = map[string]any{}
}
return m, nil
}
//export web_go_ready
func web_go_ready(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
_ = argsJSON
return replyJSON(outJSON, errMsg, map[string]any{
"ok": true,
"impl": "go",
"abi": 2,
}, nil)
}
//export web_page_new
func web_page_new(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
args, err := parseArgs(argsJSON)
if err != nil {
return replyJSON(outJSON, errMsg, nil, err)
}
return replyJSON(outJSON, errMsg, page.New(args), nil)
}