Add CGo-safe JSON methods and RunOnGoStack helper (#361)

* Add CGo-safe JSON methods and RunOnGoStack helper

When radiance types (Server, Options containing sing-box option.Outbound
with `any` interfaces) are returned to callers on a CGo callback stack,
the GC write barrier panics because the heap bitmap doesn't cover the C
stack. This caused crashes in lantern's GetAvailableServers on macOS.

Add ServersJSON() and GetServerByTagJSON() to Manager that marshal under
the lock and return plain []byte, safe for CGo callers.

Add a generic RunOnGoStack[T] helper in common/ for any remaining cases
where callers need to move pointer-rich work off the CGo stack. Includes
defer/recover so a panic returns an error instead of blocking forever.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Address PR review: tests, docstring, marshal under lock

- Add tests for ServersJSON and GetServerByTagJSON validating JSON
  output includes sing-box type-specific fields and location data
- Fix GetServerByTagJSON to perform lookup + marshal under a single
  RLock using MarshalContext with the sing-box context
- Fix RunOnGoStack docstring: clarify a new goroutine is spawned per
  call (no persistent worker)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Simplify: extract getServerByTagLocked, use MarshalContext in ServersJSON

- Extract shared lookup logic into getServerByTagLocked to eliminate
  duplication between GetServerByTag and GetServerByTagJSON
- Use json.MarshalContext in ServersJSON for consistency with
  GetServerByTagJSON (ensures sing-box type-specific fields are included)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Remove unused RunOnGoStack helper

The CGo write barrier issue is fully addressed by ServersJSON() and
GetServerByTagJSON(), which marshal pointer-rich sing-box types inside
radiance under the read lock and return plain []byte. Since no
pointer-rich Go values cross the CGo boundary, the generic goroutine
helper is unnecessary. Removing to avoid dead code.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Restore RunOffCgoStack helper in common/

Gomobile-exported functions run on a CGo callback stack whose memory
isn't covered by the GC heap bitmap. The gomobile-generated wrapper
copies Go pointer-containing return values to the C thread stack,
which can cause bulkBarrierPreWrite panics. RunOffCgoStack runs the
function body on a real Go goroutine to avoid this.

Previously named RunOnGoStack, renamed to better describe the intent.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Move RunOffCgoStack into ServersJSON and GetServerByTagJSON

Callers no longer need to wrap these methods — the goroutine hop is
handled internally so any caller (gomobile, FFI, or pure Go) is
automatically safe from CGo write barrier panics.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Document why GetServerByTag doesn't need RunOffCgoStack

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: myleshorton

common/gostack.go

@@ -0,0 +1,38 @@
+package common
+
+import (
+	"fmt"
+	"log/slog"
+	"runtime/debug"
+)
+
+// RunOffCgoStack executes fn on a new goroutine and returns its result.
+// A new goroutine is spawned per call; there is no persistent worker.
+//
+// Gomobile-exported functions run on a CGo callback stack whose memory isn't
+// covered by the GC heap bitmap. When the gomobile-generated wrapper copies Go
+// pointer-containing return values to the C thread stack, bulkBarrierPreWrite
+// can panic. Running the body on a real Go goroutine avoids this entirely.
+//
+// If fn panics, the panic is recovered and a zero value + error are returned
+// instead of blocking the caller forever.
+func RunOffCgoStack[T any](fn func() (T, error)) (T, error) {
+	type result struct {
+		val T
+		err error
+	}
+	ch := make(chan result, 1)
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				slog.Error("panic in RunOffCgoStack", "panic", r, "stack", string(debug.Stack()))
+				var zero T
+				ch <- result{val: zero, err: fmt.Errorf("panic: %v", r)}
+			}
+		}()
+		v, err := fn()
+		ch <- result{val: v, err: err}
+	}()
+	r := <-ch
+	return r.val, r.err
+}

servers/manager.go

@@ -182,11 +182,18 @@ type Server struct {
 }
 
 // GetServerByTag returns the server configuration for a given tag and a boolean indicating whether
-// the server was found.
+// the server was found. The returned Server contains pointer-rich sing-box types in its Options
+// field, so callers on a CGo callback stack should use [GetServerByTagJSON] instead. This method
+// does not use [common.RunOffCgoStack] because its only callers run on regular Go goroutines
+// (event subscribers, private server flows), never on CGo callback stacks.
 func (m *Manager) GetServerByTag(tag string) (Server, bool) {
 	m.access.RLock()
 	defer m.access.RUnlock()
+	return m.getServerByTagLocked(tag)
+}
 
+// getServerByTagLocked performs the tag lookup. Caller must hold access.RLock.
+func (m *Manager) getServerByTagLocked(tag string) (Server, bool) {
 	group := SGLantern
 	opts, ok := m.optsMaps[SGLantern][tag]
 	if !ok {
@@ -210,6 +217,41 @@ func (m *Manager) GetServerByTag(tag string) (Server, bool) {
 	return s, true
 }
 
+// ServersJSON returns the current server configurations as pre-marshalled JSON.
+// Safe to call from CGo callback stacks: the work runs on a dedicated Go goroutine
+// (via [common.RunOffCgoStack]) so pointer-rich sing-box types never touch the C stack.
+func (m *Manager) ServersJSON() ([]byte, error) {
+	return common.RunOffCgoStack(func() ([]byte, error) {
+		m.access.RLock()
+		defer m.access.RUnlock()
+		return json.MarshalContext(box.BaseContext(), m.servers)
+	})
+}
+
+// GetServerByTagJSON returns the server configuration for a given tag as pre-marshalled JSON.
+// Like [ServersJSON], safe to call from CGo callback stacks.
+func (m *Manager) GetServerByTagJSON(tag string) ([]byte, bool, error) {
+	type result struct {
+		data []byte
+		ok   bool
+	}
+	r, err := common.RunOffCgoStack(func() (result, error) {
+		m.access.RLock()
+		defer m.access.RUnlock()
+
+		s, ok := m.getServerByTagLocked(tag)
+		if !ok {
+			return result{}, nil
+		}
+		b, err := json.MarshalContext(box.BaseContext(), s)
+		if err != nil {
+			return result{}, fmt.Errorf("marshal server %q: %w", tag, err)
+		}
+		return result{data: b, ok: true}, nil
+	})
+	return r.data, r.ok, err
+}
+
 type ServersUpdatedEvent struct {
 	events.Event
 	Group   ServerGroup

servers/manager_test.go

@@ -22,6 +22,101 @@ import (
 	"github.com/getlantern/radiance/common"
 )
 
+func newTestManager(t *testing.T) *Manager {
+	t.Helper()
+	dataPath := t.TempDir()
+	mgr := &Manager{
+		servers: Servers{
+			SGLantern: Options{
+				Outbounds: []option.Outbound{
+					{Tag: "ss-denver", Type: "shadowsocks", Options: &option.ShadowsocksOutboundOptions{
+						ServerOptions: option.ServerOptions{
+							Server:     "1.2.3.4",
+							ServerPort: 1080,
+						},
+						Method:   "chacha20-ietf-poly1305",
+						Password: "testpass",
+					}},
+				},
+				Endpoints: make([]option.Endpoint, 0),
+				Locations: map[string]C.ServerLocation{
+					"ss-denver": {Country: "US", City: "Denver", CountryCode: "US"},
+				},
+				Credentials: make(map[string]ServerCredentials),
+			},
+			SGUser: Options{
+				Outbounds:   make([]option.Outbound, 0),
+				Endpoints:   make([]option.Endpoint, 0),
+				Locations:   make(map[string]C.ServerLocation),
+				Credentials: make(map[string]ServerCredentials),
+			},
+		},
+		optsMaps: map[ServerGroup]map[string]any{
+			SGLantern: {"ss-denver": option.Outbound{Tag: "ss-denver", Type: "shadowsocks", Options: &option.ShadowsocksOutboundOptions{
+				ServerOptions: option.ServerOptions{Server: "1.2.3.4", ServerPort: 1080},
+				Method:        "chacha20-ietf-poly1305",
+				Password:      "testpass",
+			}}},
+			SGUser: make(map[string]any),
+		},
+		serversFile: filepath.Join(dataPath, common.ServersFileName),
+	}
+	return mgr
+}
+
+func TestServersJSON(t *testing.T) {
+	mgr := newTestManager(t)
+
+	b, err := mgr.ServersJSON()
+	require.NoError(t, err)
+	require.NotEmpty(t, b)
+
+	// Must be valid JSON
+	var raw map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(b, &raw), "ServersJSON must return valid JSON")
+	assert.Contains(t, raw, "lantern")
+	assert.Contains(t, raw, "user")
+
+	// Lantern group must include the sing-box type-specific fields
+	lanternJSON := string(raw["lantern"])
+	assert.Contains(t, lanternJSON, "shadowsocks", "should contain outbound type")
+	assert.Contains(t, lanternJSON, "1.2.3.4", "should contain server address")
+	assert.Contains(t, lanternJSON, "1080", "should contain server port")
+	assert.Contains(t, lanternJSON, "chacha20-ietf-poly1305", "should contain method")
+}
+
+func TestGetServerByTagJSON(t *testing.T) {
+	mgr := newTestManager(t)
+
+	t.Run("existing tag", func(t *testing.T) {
+		b, ok, err := mgr.GetServerByTagJSON("ss-denver")
+		require.NoError(t, err)
+		require.True(t, ok)
+		require.NotEmpty(t, b)
+
+		// Must be valid JSON
+		var raw map[string]json.RawMessage
+		require.NoError(t, json.Unmarshal(b, &raw), "GetServerByTagJSON must return valid JSON")
+		assert.Contains(t, raw, "Tag")
+		assert.Contains(t, raw, "Type")
+		assert.Contains(t, raw, "Options")
+		assert.Contains(t, raw, "Location")
+
+		// Verify the correct tag and type
+		fullJSON := string(b)
+		assert.Contains(t, fullJSON, "ss-denver")
+		assert.Contains(t, fullJSON, "shadowsocks")
+		assert.Contains(t, fullJSON, "Denver")
+	})
+
+	t.Run("missing tag", func(t *testing.T) {
+		b, ok, err := mgr.GetServerByTagJSON("nonexistent")
+		assert.NoError(t, err)
+		assert.False(t, ok)
+		assert.Nil(t, b)
+	})
+}
+
 func TestPrivateServerIntegration(t *testing.T) {
 	dataPath := t.TempDir()
 	manager := &Manager{