Synapse 🧠

The Neural Network for Fitia's Microservices

synapse is a robust, opinionated wrapper around Go's google.golang.org/grpc client. It simplifies the complexity of establishing secure connections in cloud-native environments (Google Cloud Run & Azure Container Apps) while keeping your code readable with a functional options pattern.

Note: This repository is public to facilitate Go module imports across our microservices. It is strictly tailored to Fitia's internal infrastructure standards. Pull requests from the public may be declined if they deviate from internal requirements.

Why "Synapse"?

In the nervous system, a synapse is the structure that permits a neuron to pass an electrical signal to another neuron. In our architecture, this package handles the "signals" (RPCs) passing between our services, ensuring they are fast, secure, and properly directed.

Features

• Cloud Native Security: Automatically handles TLS negotiation and SNI (Server Name Indication) extraction—critical for connecting to services hosted on Cloud Run or Azure Container Apps.
• Lazy Connection: Built on the modern grpc.NewClient, connections are established in the background. Your application starts up instantly without waiting for dependent services to be ready.
• Functional Options: Clean, readable configuration. No more massive config structs or confusing boolean flags.
• Zero-Config Defaults: Smart normalization of addresses (e.g., handles https:// prefixes or missing ports automatically).
• Auth Injection: Built-in helper to inject Bearer tokens for service-to-service authentication.

Installation

go get github.com/fitia/synapse

Quick Start

Connect to a service using the Connect function. It returns a standard *grpc.ClientConn.

package main

import (
    "context"
    "log"
    "os"

    "github.com/fitia/synapse"
    pb "github.com/fitia/protos/users" // Example proto definition
)

func main() {
    // 1. Establish the connection
    // Synapse automatically handles TLS and address normalization
    conn, err := synapse.Connect(
        "user-service-xyz.a.run.app", 
        synapse.WithToken(os.Getenv("SERVICE_TOKEN")),
    )
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
    defer conn.Close()

    // 2. Create your standard gRPC client
    client := pb.NewUserServiceClient(conn)

    // 3. Make a request (Connection happens now)
    resp, err := client.GetUser(context.Background(), &pb.GetUserRequest{Id: "123"})
    if err != nil {
        log.Printf("Error calling user service: %v", err)
    }
}

Configuration

synapse uses the Functional Options pattern. You can mix and match these options when calling Connect.

synapse.WithToken(token string)

Injects a static Bearer token into the Authorization header of every request.

• Use Case: Service-to-Service authentication (Cloud Run/Azure Identity).

synapse.WithInsecure()

Disables TLS and connects via plaintext (HTTP/2 Cleartext).

• Use Case: Local development (localhost:50051) or connecting to a sidecar within the same pod.
• Default: False (TLS is enabled by default).

synapse.WithOptions(opts ...grpc.DialOption)

Pass any standard grpc.DialOption from the official library.

• Use Case: Adding custom interceptors, keepalive parameters, or load balancing policies.

synapse.Connect("localhost:50051", 
    synapse.WithInsecure(),
    synapse.WithOptions(grpc.WithUserAgent("fitia-backend/v2")),
)

Address Normalization

synapse is forgiving with inputs. It will automatically clean up addresses so you don't have to worry about strict formatting.

Input	Resulting Target	TLS
user-service.com	user-service.com:443	Enabled
https://api.fitia.app	api.fitia.app:443	Enabled
localhost:8080 + WithInsecure()	localhost:8080	Disabled
dns:///user-service:5000	user-service:5000	Enabled

Contributing

1. Clone the repo.
2. Create a feature branch (git checkout -b feature/retry-interceptor).
3. Commit your changes.
4. Open a Pull Request.

---

Built with ❤️ and 🥗 at Fitia