Spanner go shared core prototype

[sinhasubham]

prototype: DO NOT MERGE

[gemini-code-assist]

Code Review

This pull request introduces a prototype that offloads the hot read path of the Node Spanner client (gRPC transport, protobuf decoding, and result-set assembly) to a Go shared library loaded via a Node-API (N-API) addon. Key additions include a post-install build script, a multiplexed gRPC connection pool in Go, a C++ N-API bridge, and integration hooks in the Node.js client. The review feedback highlights several critical improvement opportunities: implementing a query cancellation mechanism to prevent resource leaks, refining authentication fallback logic to avoid silent mock token usage in production, leveraging Go's unsafe.Slice for safer pointer conversions, preventing Node-API local handle leaks using escapable handle scopes, and adding robust type validation for request arguments in the native bridge.

[gemini-code-assist]

There is currently no mechanism to propagate query cancellation from Node.js to Go. If a Node.js client destroys or cancels a stream early (e.g., due to a timeout or only reading a subset of rows), the background Go goroutine will continue running and downloading the entire result set from Spanner. This can cause significant resource leaks (CPU, memory, and network bandwidth). Exposing a cancellation mechanism or passing a query-specific context/channel to abort the gRPC stream is highly recommended.

[gemini-code-assist]

If google.DefaultTokenSource fails to initialize, silently falling back to a mock token in non-emulator/production environments can make debugging authentication issues extremely difficult. We should only fall back to the mock token if SPANNER_EMULATOR_HOST is set, and otherwise return the initialization error.

	tokenSource, err := google.DefaultTokenSource(ctx, spannerScope)
	if err != nil {
		if os.Getenv("SPANNER_EMULATOR_HOST") == "" {
			cancel()
			return nil, fmt.Errorf("failed to initialize Application Default Credentials: %w", err)
		}
		// In mock/test environments without ADC, allow fallback
		tokenSource = oauth2.StaticTokenSource(&oauth2.Token{
			AccessToken: "mock-token",
			TokenType:   "Bearer",
		})
	}

[gemini-code-assist]

Using unsafe.Slice (introduced in Go 1.17) is much cleaner, safer, and more idiomatic than slicing a pointer cast to a very large array (e.g., *[1 << 28]C.CSpannerCell). Since this module declares go 1.25, we should leverage unsafe.Slice directly.

Suggested change

	cellsSlice := (*[1 << 28]C.CSpannerCell)(unsafe.Pointer(cBatch.cells))[:totalCells:totalCells]
	cellsSlice := unsafe.Slice(cBatch.cells, totalCells)

[gemini-code-assist]

Use unsafe.Slice to safely and cleanly convert the C string arena pointer to a Go byte slice.

Suggested change

	arenaBytes = (*[1 << 28]byte)(unsafe.Pointer(cBatch.string_arena))[:totalStringBytes:totalStringBytes]
	arenaBytes = unsafe.Slice((*byte)(unsafe.Pointer(cBatch.string_arena)), totalStringBytes)

[gemini-code-assist]

Use unsafe.Slice to cleanly convert the C metadata keys and values pointers to Go slices.

Suggested change

	keysSlice := (*[1 << 28]*C.char)(unsafe.Pointer(metaKeys))[:count:count]
	valsSlice := (*[1 << 28]*C.char)(unsafe.Pointer(metaVals))[:count:count]
	keysSlice := unsafe.Slice(metaKeys, count)
	valsSlice := unsafe.Slice(metaVals, count)

[gemini-code-assist]

When creating a large number of JavaScript objects in a loop (such as rows and cells in a query result), Node-API local handles can accumulate rapidly and exceed V8's local handle limit or cause unnecessary memory overhead. To prevent handle leaks, we should use napi_escapable_handle_scope for each row, and escape the row array before closing the scope.

                for (int r = 0; r < row_count; ++r) {
                    napi_escapable_handle_scope scope;
                    napi_open_escapable_handle_scope(env, &scope);

                    napi_value row_arr;
                    napi_create_array_with_length(env, col_count, &row_arr);

                    for (int c = 0; c < col_count; ++c) {
                        const CSpannerCell& cell = cells[r * col_count + c];
                        napi_value js_cell = nullptr;

                        switch (cell.kind) {
                            case CELL_KIND_NULL:
                                napi_get_null(env, &js_cell);
                                break;
                            case CELL_KIND_BOOL:
                                napi_get_boolean(env, cell.bool_val != 0, &js_cell);
                                break;
                            case CELL_KIND_NUMBER:
                                napi_create_double(env, cell.number_val, &js_cell);
                                break;
                            case CELL_KIND_STRING:
                                if (cell.str_len > 0 && cell.str_val != nullptr) {
                                    napi_create_string_utf8(env, cell.str_val, cell.str_len, &js_cell);
                                } else {
                                    napi_create_string_utf8(env, "", 0, &js_cell);
                                }
                                break;
                            default:
                                napi_get_null(env, &js_cell);
                                break;
                        }
                        napi_set_element(env, row_arr, c, js_cell);
                    }
                    napi_value escaped_row_arr;
                    napi_escape_handle(env, scope, row_arr, &escaped_row_arr);
                    napi_close_escapable_handle_scope(env, scope);

                    napi_set_element(env, rows_val, r, escaped_row_arr);
                }

[gemini-code-assist]

If args[3] is neither a TypedArray nor a Buffer, we should throw a clear type error on the JavaScript side rather than silently proceeding with req_data = nullptr and req_len = 0, which would eventually cause a decoding failure or potential panic in Go.

Suggested change

	bool is_typedarray = false;
	napi_is_typedarray(env, args[3], &is_typedarray);
	if (is_typedarray) {
	napi_typedarray_type type;
	napi_value arraybuffer;
	size_t byte_offset;
	napi_get_typedarray_info(env, args[3], &type, &req_len, &req_data, &arraybuffer, &byte_offset);
	} else {
	bool is_buffer = false;
	napi_is_buffer(env, args[3], &is_buffer);
	if (is_buffer) {
	napi_get_buffer_info(env, args[3], &req_data, &req_len);
	}
	}
	bool is_typedarray = false;
	napi_is_typedarray(env, args[3], &is_typedarray);
	if (is_typedarray) {
	napi_typedarray_type type;
	napi_value arraybuffer;
	size_t byte_offset;
	napi_get_typedarray_info(env, args[3], &type, &req_len, &req_data, &arraybuffer, &byte_offset);
	} else {
	bool is_buffer = false;
	napi_is_buffer(env, args[3], &is_buffer);
	if (is_buffer) {
	napi_get_buffer_info(env, args[3], &req_data, &req_len);
	} else {
	napi_throw_type_error(env, nullptr, "Argument 3 must be a TypedArray or Buffer");
	return nullptr;
	}
	}