Skip to content

PROJECT_SUMMARY.md

Latest commit

 

History

History
225 lines (184 loc) · 5.63 KB

PROJECT_SUMMARY.md

File metadata and controls

225 lines (184 loc) · 5.63 KB

Trusera SDK Go - Project Summary

Overview

Complete Go SDK for monitoring AI agents with Trusera's Cedar-based policy engine.

Repository: github.com/Trusera/trusera-sdk-go

Key Features

  • Zero external dependencies (stdlib only)
  • HTTP client interception for monitoring outbound requests
  • Three enforcement modes: log, warn, block
  • Background event batching and flushing
  • Thread-safe concurrent operations
  • 85.4% test coverage
  • Comprehensive examples

Package Structure

Core Files (490 lines)

trusera.go (218 lines)

Main client implementation:

  • Client struct with mutex-protected event queue
  • Background flusher goroutine
  • Option pattern for configuration
  • NewClient(), Track(), Flush(), RegisterAgent(), Close()
  • Default values: 30s flush interval, 100 event batch size

events.go (66 lines)

Event types and creation:

  • 6 event types: tool_call, llm_invoke, data_access, api_call, file_write, decision
  • Event struct with ID, Type, Name, Payload, Metadata, Timestamp
  • NewEvent() with auto-generated ID (crypto/rand hex)
  • Builder pattern: WithPayload(), WithMetadata()

interceptor.go (206 lines)

HTTP interception logic:

  • EnforcementMode: Log, Warn, Block
  • InterceptorOptions with exclude/block patterns
  • WrapHTTPClient() - wraps http.Client with interception
  • interceptingTransport implements http.RoundTripper
  • Header sanitization (redacts Authorization, Cookie, X-Api-Key)
  • Request body capture (500 byte limit)
  • Convenience helpers: CreateInterceptedClient(), InterceptDefault(), MustRegisterAndIntercept()

Test Files (19 tests, 1570 lines)

trusera_test.go (253 lines)

  • Client creation and options
  • Event tracking and flushing
  • Agent registration
  • Background flusher
  • Auto-flush on batch size
  • Thread safety

events_test.go (133 lines)

  • Event creation and uniqueness
  • Builder pattern
  • JSON serialization
  • All event types

interceptor_test.go (295 lines)

  • HTTP interception
  • All enforcement modes
  • Exclude/block patterns
  • Header sanitization
  • Concurrent requests
  • Body capture

Test Results: All 19 tests pass, 85.4% coverage

Examples

basic/main.go

  • Client creation
  • Tracking tool calls, LLM invocations, data access, decisions
  • Manual flushing

http-interceptor/main.go

  • HTTP client wrapping
  • Warn mode enforcement
  • Exclude/block patterns
  • POST requests

block-mode/main.go

  • Block mode enforcement
  • MustRegisterAndIntercept helper
  • Error handling for blocked requests

Configuration Files

go.mod

module github.com/Trusera/trusera-sdk-go
go 1.21

Zero external dependencies.

.golangci.yml

Enabled linters: errcheck, gosimple, govet, ineffassign, staticcheck, unused, gofmt, goimports, misspell, unconvert, goconst, gocyclo, dupl

.github/workflows/ci.yml

  • Test on Go 1.21, 1.22, 1.23
  • Lint with golangci-lint
  • Build verification
  • Security scan with gosec
  • Coverage upload to Codecov

Documentation

README.md (7655 bytes)

  • Installation
  • Quickstart (3 lines)
  • HTTP interceptor examples
  • Enforcement modes
  • Event types
  • Configuration options
  • API reference
  • Thread safety

QUICKSTART.md

  • 5-minute guide
  • Basic tracking example
  • HTTP interception example
  • Block mode example

CONTRIBUTING.md (5533 bytes)

  • Development setup
  • Testing guidelines
  • Code style
  • PR process
  • Project structure

CHANGELOG.md

  • Version history
  • Feature list
  • Release notes

API Surface

Client

func NewClient(apiKey string, opts ...Option) *Client
func (c *Client) Track(event Event)
func (c *Client) Flush() error
func (c *Client) RegisterAgent(name, framework string) (string, error)
func (c *Client) Close() error

Options

func WithBaseURL(url string) Option
func WithAgentID(id string) Option
func WithFlushInterval(d time.Duration) Option
func WithBatchSize(n int) Option

Events

func NewEvent(eventType EventType, name string) Event
func (e Event) WithPayload(key string, value any) Event
func (e Event) WithMetadata(key string, value any) Event

Interceptor

func WrapHTTPClient(client *http.Client, truseraClient *Client, opts InterceptorOptions) *http.Client
func CreateInterceptedClient(truseraClient *Client, opts InterceptorOptions) *http.Client
func InterceptDefault(truseraClient *Client, opts InterceptorOptions)
func MustRegisterAndIntercept(apiKey, agentName, framework string, opts InterceptorOptions) (*Client, *http.Client, error)

Verification

All checks passing:

  • ✓ go test ./... - 19/19 tests pass
  • ✓ go test -cover ./... - 85.4% coverage
  • ✓ go fmt ./... - formatted
  • ✓ go vet ./... - no issues
  • ✓ go build ./... - compiles
  • ✓ All examples compile
  • ✓ Zero external dependencies
  • ✓ Thread-safe operations

File Statistics

Category Files Lines
Core 3 490
Tests 3 1570
Examples 3 ~300
Docs 5 ~1000
Config 3 ~100
Total 17 ~3500

Usage Example

// Create and register
client, httpClient, _ := trusera.MustRegisterAndIntercept(
    "api-key",
    "my-agent",
    "langchain",
    trusera.InterceptorOptions{
        Enforcement: trusera.ModeBlock,
        BlockPatterns: []string{"malicious.com"},
    },
)
defer client.Close()

// Track events
client.Track(trusera.NewEvent(trusera.EventToolCall, "search").
    WithPayload("query", "AI security"))

// HTTP requests auto-monitored
httpClient.Get("https://api.example.com")

Next Steps

  1. Publish to GitHub: github.com/Trusera/trusera-sdk-go
  2. Tag v0.1.0 release
  3. Submit to pkg.go.dev
  4. Add to Trusera docs
  5. Create integration examples with popular frameworks