Add go implementation

.github/copilot-instructions.md

@@ -7,7 +7,7 @@ This document provides guidance for AI agents working within the Telepact codeba
 Telepact is a multi-language API ecosystem built around a unified schema definition. The core idea is to define your API in `.telepact.json` files, and then use language-specific libraries to implement clients and servers.
 
 The project is a monorepo containing several independent but related components:
--   **Core Libraries (`/lib`)**: Implementations of the Telepact protocol in `java`, `py` (Python), and `ts` (TypeScript). These provide the `Server` and `Client` classes.
+-   **Core Libraries (`/lib`)**: Implementations of the Telepact protocol in `go`, `java`, `py` (Python), and `ts` (TypeScript). These provide the `Server` and `Client` classes.
 -   **SDKs (`/sdk`)**: Tools built on top of the core libraries, including a `cli`, a web-based `console`, and a `prettier` plugin for formatting schema files.
 -   **Bindings (`/bind`)**: Language-specific bindings, like for `dart`.
 -   **Schema Definitions**: APIs are defined in `.telepact.json` files (e.g., `common/auth.telepact.json`). These files are the source of truth for all API interactions.
@@ -20,7 +20,6 @@ The entire project uses a hierarchical `Makefile` system. The root `Makefile` de
 
 ### Building
 
--   To build everything: `make` (though this is often not necessary).
 -   To build a specific library, navigate to its directory or use the root makefile. For example, to build the Java library:
     ```sh
     make java
@@ -31,33 +30,18 @@ The entire project uses a hierarchical `Makefile` system. The root `Makefile` de
 
 ### Testing
 
-The central test runner is located in `/test/runner`, which is a Python project. It is responsible for orchestrating tests across all language libraries to ensure they are interoperable.
-
--   To run all tests:
-    ```sh
-    make test
-    ```
--   To run tests for a specific language:
+-   Run tests from the `/test/runner` directory:
     ```sh
-    make test-java
-    make test-py
-    make test-ts
+    poetry run python -m pytest -s -vv -k <test_name>
     ```
--   When in the `/test/runner` directory, you can run tests directly with `poetry run python -m pytest`.
 
--   To run a single test case (e.g., for debugging), use `pytest`'s `-k` option to select a test by name. The `test/runner/Makefile` has `test-trace-*` targets that are good examples:
-    ```sh
-    # From the root directory
-    make test-trace-java
-
-    # Or, from the test/runner directory
-    poetry run python -m pytest -k test_client_server_case[java-0] -s -vv
-    ```
+-   NOTE: You need the `-s` flag to show all request/response payloads for debugging.
+    HOWEVER, avoid using `-s` when `-k` is not specified, as it will produce excessive output.
 
 ### Key Files & Directories
 
 -   `Makefile`: The entry point for all build, test, and deploy operations.
--   `lib/{java,py,ts}`: The core libraries. Changes here impact the fundamental behavior of Telepact.
+-   `lib/{go,java,py,ts}`: The core libraries. Changes here impact the fundamental behavior of Telepact.
 -   `bind/dart`: Language-specific bindings for Dart.
 -   `test/runner`: The cross-language integration test suite. This is the best place to understand how different language implementations are expected to behave and interact.
 -   `common/*.telepact.json`: The common schema files that define the internal APIs used by Telepact itself.

.github/workflows/build.yml

@@ -119,6 +119,22 @@ jobs:
           path: lib/java/target
           retention-days: 1
 
+  build-go:
+    name: Build Go
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - name: Build go
+        run: make go
+
   build-py:
     name: Build Python
     runs-on: ubuntu-latest
@@ -382,7 +398,7 @@ jobs:
     name: Test
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    needs: [build-ts, build-java, build-py, build-cli]
+    needs: [build-ts, build-java, build-go, build-py, build-cli]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.github/workflows/publish.yml

@@ -91,6 +91,24 @@ jobs:
           POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
         run: make deploy-py
 
+  publish-go:
+    runs-on: ubuntu-latest
+    if: ${{ contains(github.event.release.body, '- go') }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.target_commitish }}
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - name: Publish to Go proxy
+        run: make deploy-go
+
   publish-cli:
     runs-on: ubuntu-latest
     if: ${{ contains(github.event.release.body, '- cli') }}

Makefile

@@ -64,6 +64,21 @@ test-trace-ts:
 deploy-ts:
 	$(MAKE) -C lib/ts deploy
 
+go:
+	$(MAKE) -C lib/go
+
+clean-go:
+	$(MAKE) -C lib/go clean
+
+test-go:
+	$(MAKE) -C test/runner test-go
+
+test-trace-go:
+	$(MAKE) -C test/runner test-trace-go
+
+deploy-go:
+	$(MAKE) -C lib/go deploy
+
 .PHONY: test
 test:
 	$(MAKE) -C test/runner test
@@ -72,6 +87,7 @@ clean-test:
 	$(MAKE) -C test/runner clean
 	$(MAKE) -C test/lib/java clean
 	$(MAKE) -C test/lib/py clean
+	$(MAKE) -C test/lib/go clean
 	$(MAKE) -C test/lib/ts clean
 
 dart:

README.md

@@ -27,6 +27,7 @@ the library and SDK docs:
 -   [Library: Typescript](./lib/ts/README.md)
 -   [Library: Python](./lib/py/README.md)
 -   [Library: Java](./lib/java/README.md)
+-   [Library: Go](./lib/go/README.md)
 
 -   [SDK: CLI](./sdk/cli/README.md)
 -   [SDK: Developer Console](./sdk/console/README.md)

lib/go/Client.go

@@ -0,0 +1,133 @@
+//|
+//|  Copyright The Telepact Authors
+//|
+//|  Licensed 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
+//|
+//|  https://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 telepact
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	telepactinternal "github.com/telepact/telepact/lib/go/internal"
+	"github.com/telepact/telepact/lib/go/internal/binary"
+)
+
+// ClientAdapter is the transport-specific function used to exchange Telepact messages.
+type ClientAdapter func(ctx context.Context, request Message, serializer *Serializer) (Message, error)
+
+// ClientOptions configure a Client instance.
+type ClientOptions struct {
+	UseBinary         bool
+	AlwaysSendJSON    bool
+	TimeoutMSDefault  int
+	SerializationImpl Serialization
+}
+
+// NewClientOptions returns a ClientOptions struct populated with library defaults.
+func NewClientOptions() *ClientOptions {
+	return &ClientOptions{
+		UseBinary:         false,
+		AlwaysSendJSON:    true,
+		TimeoutMSDefault:  5000,
+		SerializationImpl: NewDefaultSerialization(),
+	}
+}
+
+// Client coordinates request/response interactions with a Telepact service.
+type Client struct {
+	adapter          ClientAdapter
+	useBinaryDefault bool
+	alwaysSendJSON   bool
+	timeoutMSDefault int
+	serializer       *Serializer
+}
+
+// NewClient constructs a Client using the provided adapter and options.
+func NewClient(adapter ClientAdapter, options *ClientOptions) (*Client, error) {
+	if adapter == nil {
+		return nil, errors.New("telepact: client adapter must not be nil")
+	}
+
+	if options == nil {
+		options = NewClientOptions()
+	}
+
+	serializationImpl := options.SerializationImpl
+	if serializationImpl == nil {
+		serializationImpl = NewDefaultSerialization()
+	}
+
+	binaryEncodingCache := binary.NewDefaultBinaryEncodingCache()
+	binaryEncoder := binary.NewClientBinaryEncoder(binaryEncodingCache)
+	base64Encoder := binary.NewClientBase64Encoder()
+	serializer := NewSerializer(serializationImpl, binaryEncoder, base64Encoder)
+
+	return &Client{
+		adapter:          adapter,
+		useBinaryDefault: options.UseBinary,
+		alwaysSendJSON:   options.AlwaysSendJSON,
+		timeoutMSDefault: options.TimeoutMSDefault,
+		serializer:       serializer,
+	}, nil
+}
+
+// RequestWithContext executes the adapter using the supplied context, applying Telepact defaults.
+func (c *Client) RequestWithContext(ctx context.Context, request Message) (Message, error) {
+	if c == nil {
+		return Message{}, NewTelepactError("telepact: client is nil")
+	}
+
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	internalRequest := telepactinternal.NewClientMessage(request.Headers, request.Body)
+
+	adapter := func(ctx context.Context, msg *telepactinternal.ClientMessage) (*telepactinternal.ClientMessage, error) {
+		resp, err := c.adapter(ctx, Message{Headers: msg.Headers, Body: msg.Body}, c.serializer)
+		if err != nil {
+			return nil, err
+		}
+		return telepactinternal.NewClientMessage(resp.Headers, resp.Body), nil
+	}
+
+	internalResponse, err := telepactinternal.ClientHandleMessage(
+		ctx,
+		internalRequest,
+		adapter,
+		c.timeoutMSDefault,
+		c.useBinaryDefault,
+		c.alwaysSendJSON,
+	)
+	if err != nil {
+		return Message{}, NewTelepactError(fmt.Sprintf("client request failed: %v", err))
+	}
+
+	return Message{Headers: internalResponse.Headers, Body: internalResponse.Body}, nil
+}
+
+// Request executes the adapter using a background context.
+func (c *Client) Request(request Message) (Message, error) {
+	return c.RequestWithContext(context.Background(), request)
+}
+
+// Serializer returns the serializer associated with the client.
+func (c *Client) Serializer() *Serializer {
+	if c == nil {
+		return nil
+	}
+	return c.serializer
+}