feat(go): initialize a minimal Go module and CI workflow for the upcoming Go SDK

.github/workflows/go.yml

@@ -0,0 +1,55 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: GraphAr Go CI
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'go/graphar/**'
+      - '.github/workflows/go.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'go/graphar/**'
+      - '.github/workflows/go.yml'
+
+concurrency:
+  group: ${{ github.repository }}-${{ github.event.number || github.head_ref || github.sha }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  go-test:
+    name: Go 1.21
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.event.pull_request.title, 'WIP') && !github.event.pull_request.draft }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+          cache: true
+          cache-dependency-path: go/graphar/go.sum
+
+      - name: Go test
+        working-directory: go/graphar
+        run: go test ./...

go/graphar/Makefile

@@ -0,0 +1,22 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+.PHONY: test
+
+test:
+	go test ./...
+

go/graphar/go.mod

@@ -0,0 +1,22 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+module github.com/apache/incubator-graphar/go/graphar
+
+go 1.21
+
+require gopkg.in/yaml.v3 v3.0.1

go/graphar/go.sum

@@ -0,0 +1,4 @@
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

go/graphar/graphar.go

@@ -0,0 +1,90 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package graphar
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/apache/incubator-graphar/go/graphar/info"
+)
+
+// FileSystem defines a minimal interface for reading files.
+// It matches the requirements for loading GraphAr info files.
+type FileSystem interface {
+	// ReadFile reads the named file and returns the contents.
+	ReadFile(ctx context.Context, name string) ([]byte, error)
+}
+
+// GraphAr is the main entry point for using the GraphAr Go SDK.
+type GraphAr interface {
+	// LoadGraphInfo loads a graph-level Info YAML (plus referenced vertex/edge info files)
+	// using the configured FileSystem.
+	LoadGraphInfo(ctx context.Context, path string) (*info.GraphInfo, error)
+}
+
+type client struct {
+	fs FileSystem
+}
+
+// option configures the GraphAr instance.
+type option func(*client)
+
+// WithFileSystem sets a custom FileSystem for the GraphAr instance.
+func WithFileSystem(fs FileSystem) option {
+	return func(c *client) {
+		c.fs = fs
+	}
+}
+
+// New creates a new GraphAr instance.
+func New(opts ...option) GraphAr {
+	c := &client{}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(c)
+		}
+	}
+	return c
+}
+
+// LoadGraphInfo loads a graph-level Info YAML (plus referenced vertex/edge
+// info files) using the configured FileSystem.
+func (c *client) LoadGraphInfo(ctx context.Context, path string) (*info.GraphInfo, error) {
+	var g *info.GraphInfo
+	var err error
+
+	if c.fs != nil {
+		// If custom FS is provided, we need to load via reader
+		b, err := c.fs.ReadFile(ctx, path)
+		if err != nil {
+			return nil, fmt.Errorf("graphar: read graph info %q from fs: %w", path, err)
+		}
+		// We'll need to update info.LoadGraphInfo to accept a loader or use a simplified version
+		g, err = info.LoadGraphInfoFromBytes(b, path, func(p string) ([]byte, error) {
+			return c.fs.ReadFile(ctx, p)
+		})
+	} else {
+		g, err = info.LoadGraphInfo(path)
+	}
+
+	if err != nil {
+		return nil, fmt.Errorf("graphar: load graph info %q: %w", path, err)
+	}
+	return g, nil
+}

go/graphar/graphar_client_test.go

@@ -0,0 +1,82 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package graphar
+
+import (
+	"context"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+func getRepoRoot() string {
+	_, filename, _, _ := runtime.Caller(0)
+	// current file: go/graphar/graphar_client_test.go
+	return filepath.Join(filepath.Dir(filename), "..", "..")
+}
+
+func TestNewClient(t *testing.T) {
+	t.Run("default", func(t *testing.T) {
+		c := New()
+		if c == nil {
+			t.Fatalf("expected non-nil client")
+		}
+	})
+
+	t.Run("with options", func(t *testing.T) {
+		called := false
+		opt := func(c *client) {
+			called = true
+		}
+		c := New(opt, nil)
+		if c == nil {
+			t.Fatalf("expected non-nil client")
+		}
+		if !called {
+			t.Errorf("expected option to be called")
+		}
+	})
+}
+
+func TestClientLoadGraphInfoErrors(t *testing.T) {
+	c := New()
+	_, err := c.LoadGraphInfo(context.Background(), "non-existent-path.yml")
+	if err == nil {
+		t.Errorf("expected error for non-existent path")
+	}
+}
+
+func TestClientLoadGraphInfo(t *testing.T) {
+	root := getRepoRoot()
+	graphPath := filepath.Join(root, "testing", "modern_graph", "modern_graph.graph.yml")
+
+	c := New()
+	g, err := c.LoadGraphInfo(context.Background(), graphPath)
+	if err != nil {
+		t.Fatalf("LoadGraphInfo failed: %v", err)
+	}
+	if g.Name != "modern_graph" {
+		t.Fatalf("unexpected graph name: %s", g.Name)
+	}
+	if !g.HasVertex("person") {
+		t.Fatalf("expected graph to have vertex person")
+	}
+	if !g.HasEdge("person", "knows", "person") {
+		t.Fatalf("expected graph to have edge person-knows-person")
+	}
+}

go/graphar/graphar_test.go

@@ -0,0 +1,78 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package graphar
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+func TestNew(t *testing.T) {
+	t.Parallel()
+
+	c := New()
+	if c == nil {
+		t.Fatalf("New() returned nil")
+	}
+}
+
+type mockFS struct {
+	files map[string][]byte
+}
+
+func (m *mockFS) ReadFile(ctx context.Context, name string) ([]byte, error) {
+	if b, ok := m.files[name]; ok {
+		return b, nil
+	}
+	return nil, errors.New("file not found")
+}
+
+func TestClientWithFileSystem(t *testing.T) {
+	fs := &mockFS{
+		files: map[string][]byte{
+			"graph.yaml": []byte(`
+name: test_graph
+prefix: /tmp/
+vertices: [v.yaml]
+edges: []
+version: 0.1.0
+`),
+			"v.yaml": []byte(`
+type: person
+chunk_size: 100
+prefix: person/
+property_groups: []
+version: 0.1.0
+`),
+		},
+	}
+
+	c := New(WithFileSystem(fs))
+	g, err := c.LoadGraphInfo(context.Background(), "graph.yaml")
+	if err != nil {
+		t.Fatalf("LoadGraphInfo failed: %v", err)
+	}
+
+	if g.Name != "test_graph" {
+		t.Errorf("expected name test_graph, got %s", g.Name)
+	}
+	if len(g.VertexInfos) != 1 {
+		t.Errorf("expected 1 vertex info, got %d", len(g.VertexInfos))
+	}
+}