SDK Configuration

This page covers configuration options for Mesh SDK clients. All generated SDK clients follow the same patterns and provide consistent configuration options regardless of the specific service.

Client Configuration Patterns

All Mesh SDK clients are generated from the same template per language and provide consistent configuration options across Go, Python, Java, and TypeScript implementations. You can configure:

Connection settings - URL, port, TLS/SSL options
Authentication - API key, group ID, or environment-based credentials
Timeouts - Request and connection timeouts

Go
Python
Java
TypeScript (Node)
TypeScript (Web)

client-config.go
package main

import (
	"context"
	"log"
	"time"

	api_userv1 "github.com/meshtrade/api/go/iam/api_user/v1"
)

func main() {
	// Option 1: Zero configuration (auto-discovers credentials, connects to Mesh API)
	client1, err := api_userv1.NewApiUserServiceGRPCClient()
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client1.Close()

	// Option 2: Direct API key and group configuration
	client2, err := api_userv1.NewApiUserServiceGRPCClient(
		api_userv1.WithAPIKey("your-api-key-here"),
		api_userv1.WithGroup("groups/your-group-id"),
	)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client2.Close()

	// Option 3: Full custom configuration
	client3, err := api_userv1.NewApiUserServiceGRPCClient(
		api_userv1.WithAddress("custom-endpoint.example.com", 443),
		api_userv1.WithTLS(true),
		api_userv1.WithTimeout(30*time.Second),
		api_userv1.WithAPIKey("your-api-key-here"),
		api_userv1.WithGroup("groups/your-group-id"),
	)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client3.Close()

	// All clients have the same interface
	ctx := context.Background()
	response, err := client1.ListApiUsers(ctx, &api_userv1.ListApiUsersRequest{})
	if err != nil {
		log.Fatalf("Failed to list users: %v", err)
	}
	log.Printf("Found %d API users", len(response.ApiUsers))
}

Go Configuration Options:

Option	Default	Description
`WithAddress(host, port)`	`Mesh API endpoint`, `443`	Custom host and port
`WithTLS(enabled)`	`true`	Enable/disable TLS
`WithAPIKey(key)`	Auto-discovered	API key for authentication
`WithGroup(groupID)`	Auto-discovered	Group context (`groups/{id}`)
`WithTimeout(duration)`	`30s`	Request timeout
`WithTracer(tracer)`	None	OpenTelemetry tracer

client-config.py
from meshtrade.iam.api_user.v1 import (
    ApiUserServiceGRPCClient,
    ClientOptions,
    ListApiUsersRequest,
)

def main():
    # Option 1: Zero configuration (auto-discovers credentials, connects to Mesh API)
    client1 = ApiUserServiceGRPCClient(ClientOptions())

    # Option 2: Direct API key and group configuration
    client2 = ApiUserServiceGRPCClient(ClientOptions(
        api_key="your-api-key-here",
        group="groups/your-group-id",
    ))

    # Option 3: Full custom configuration
    client3 = ApiUserServiceGRPCClient(ClientOptions(
        url="custom-endpoint.example.com",
        port=443,
        tls=True,
        timeout=30.0,
        api_key="your-api-key-here",
        group="groups/your-group-id",
    ))

    # All clients have the same interface
    with client1:
        response = client1.list_api_users(ListApiUsersRequest())
        print(f"Found {len(response.api_users)} API users")

if __name__ == "__main__":
    main()

Python Configuration Options:

Option	Default	Description
`url`	`Mesh API endpoint`	Host/endpoint
`port`	`443`	Port number
`tls`	`True`	Enable/disable TLS
`api_key`	Auto-discovered	API key for authentication
`group`	Auto-discovered	Group context (`groups/{id}`)
`timeout`	`30.0`	Request timeout in seconds

ClientConfig.java
import co.meshtrade.api.config.ServiceOptions;
import co.meshtrade.api.iam.api_user.v1.ApiUserServiceGRPCClient;
import java.time.Duration;

public class ClientConfig {
    public static void main(String[] args) {
        // Option 1: Zero configuration (auto-discovers credentials, connects to Mesh API)
        ApiUserServiceGRPCClient client1 = new ApiUserServiceGRPCClient(
            ServiceOptions.builder().build()
        );

        // Option 2: Direct API key and group configuration
        ApiUserServiceGRPCClient client2 = new ApiUserServiceGRPCClient(
            ServiceOptions.builder()
                .apiKey("your-api-key-here")
                .group("groups/your-group-id")
                .build()
        );

        // Option 3: Full custom configuration
        ApiUserServiceGRPCClient client3 = new ApiUserServiceGRPCClient(
            ServiceOptions.builder()
                .url("custom-endpoint.example.com")
                .port(443)
                .tls(true)
                .timeout(Duration.ofSeconds(60))
                .apiKey("your-api-key-here")
                .group("groups/your-group-id")
                .build()
        );
    }
}

Java Configuration Options:

Option	Default	Description
`.url(String)`	Mesh API endpoint	gRPC server URL
`.port(int)`	`443`	gRPC server port
`.tls(boolean)`	`true`	Enable/disable TLS
`.timeout(Duration)`	`30s`	Request timeout
`.apiKey(String)`	Auto-discovered	API key for authentication
`.group(String)`	Auto-discovered	Group context (`groups/{id}`)
`.groupId(String)`	-	Convenience method (auto-adds `groups/` prefix)

client-config.ts
import { ApiUserServiceNode } from "@meshtrade/api-node/iam/api_user/v1";
import {
  WithAPIKey,
  WithGroup,
  WithServerUrl,
} from "@meshtrade/api-node/config";

// Option 1: Minimal client (defaults to Mesh API endpoint)
const client1 = new ApiUserServiceNode(
  WithAPIKey("your-api-key-here"),
  WithGroup("groups/your-group-id"),
);

// Option 2: Custom server URL
const client2 = new ApiUserServiceNode(
  WithServerUrl("https://custom-endpoint.example.com"),
  WithAPIKey("your-api-key-here"),
  WithGroup("groups/your-group-id"),
);

TypeScript Node Configuration Options:

Option	Default	Description
`WithServerUrl(url)`	Mesh API endpoint	Server URL (include protocol)
`WithAPIKey(key)`	None	API key authentication
`WithGroup(group)`	None	Group context (`groups/{id}`)

note

The TypeScript Node SDK does not support automatic credential discovery. Credentials must be provided explicitly.

client-config-web.ts
import { ApiUserServiceGrpcWebClientV1 } from "@meshtrade/api-old/iam/api_user/v1";

// Option 1: Default connection (uses Mesh API endpoint)
const client1 = new ApiUserServiceGrpcWebClientV1();

// Option 2: Custom server URL
const client2 = new ApiUserServiceGrpcWebClientV1({
  apiServerURL: "https://custom-endpoint.example.com",
});

// Option 3: With group context
const client3 = client2.withGroup("groups/your-group-id");

TypeScript Web Configuration Options:

Option	Default	Description
`apiServerURL`	Mesh API endpoint	API server URL
`.withGroup(group)`	None	Returns a new client with group context

note

The TypeScript Web SDK uses gRPC-Web and is designed for browser environments. Authentication is typically handled via browser cookies (withCredentials: true).

Authentication Methods

Automatic Credential Discovery (Go, Python, Java)

The Go, Python, and Java SDKs automatically discover credentials from the filesystem. Place your credentials.json in the platform-specific directory:

Linux: ~/.config/mesh/credentials.json
macOS: ~/Library/Application Support/mesh/credentials.json
Windows: C:\Users\<user>\AppData\Roaming\mesh\credentials.json

Or set the MESH_API_CREDENTIALS environment variable:

export MESH_API_CREDENTIALS=/path/to/your/credentials.json

credentials.json
{
  "api_key": "your-api-key-here",
  "group_id": "groups/your-group-id"
}

Direct Configuration

For programmatic control, set credentials directly in the client options:

API Key - Your authentication token
Group ID - The group context (format: groups/your-group-id)

Connection Management

All generated clients include proper connection management:

Go: Use defer client.Close() to ensure cleanup
Python: Use with client: context manager for automatic cleanup
Java: Use try-with-resources or explicit close
TypeScript: No explicit cleanup required

Error Handling

All clients follow consistent error handling patterns:

Go: Returns error as second value
Python: Raises exceptions
Java: Throws exceptions
TypeScript: Returns promises (use async/await with try/catch)

Advanced Features

OpenTelemetry Tracing (Go SDK)

The Go SDK supports distributed tracing:

import (
    "go.opentelemetry.io/otel"
    api_userv1 "github.com/meshtrade/api/go/iam/api_user/v1"
)

tracer := otel.Tracer("my-application")
client, err := api_userv1.NewApiUserServiceGRPCClient(
    api_userv1.WithTracer(tracer),
)

Context Timeouts (Go SDK)

The Go SDK respects context deadlines, allowing per-request timeout control:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

response, err := client.GetApiUser(ctx, request)

Client Configuration Patterns​

Authentication Methods​

Automatic Credential Discovery (Go, Python, Java)​

Direct Configuration​

Connection Management​

Error Handling​

Advanced Features​

OpenTelemetry Tracing (Go SDK)​

Context Timeouts (Go SDK)​