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:
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.
@@ -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/`(勿再演进)。
|
||||
@@ -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 */
|
||||
@@ -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 */
|
||||
@@ -0,0 +1,3 @@
|
||||
module github.com/marqdo/marqdo/plugins/web
|
||||
|
||||
go 1.24.5
|
||||
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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) }
|
||||
@@ -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)
|
||||
}
|
||||
Reference in new issue
Block a user