Cursor rule

1---
2description: Core Go patterns and conventions required for Compozy development
3globs: **/*.go
4alwaysApply: true
5---
6# Core Go Patterns & Conventions
7 
8## Concurrency Patterns
9 
10<pattern type="thread_safe_structures">
11```go
12// Thread-safe structs with embedded mutex
13type Status struct {
14    Name   string
15    mu     sync.RWMutex // Protects all fields
16}
17```
18</pattern>
19 
20<pattern type="concurrent_operations">
21```go
22// Concurrent operations with errgroup
23g, ctx := errgroup.WithContext(ctx)
24for _, item := range items {
25    item := item // capture loop variable
26    g.Go(func() error { return process(ctx, item) })
27}
28return g.Wait()
29```
30</pattern>
31 
32## Factory Pattern (OCP Implementation)
33 
34<requirement type="mandatory">
35**MANDATORY for service creation:**
36</requirement>
37 
38<pattern type="factory_implementation">
39```go
40// ✅ Good: Extensible through interfaces
41type Storage interface {
42    Save(ctx context.Context, data []byte) error
43}
44 
45type StorageFactory struct{}
46func (f *StorageFactory) CreateStorage(storageType string) (Storage, error) {
47    switch storageType {
48    case "redis": return NewRedisStorage(), nil
49    case "memory": return NewMemoryStorage(), nil
50    default: return nil, fmt.Errorf("unsupported storage type: %s", storageType)
51    }
52}
53 
54// Usage in constructors
55func NewStorage(config *StorageConfig) (Storage, error) {
56    factory := &StorageFactory{}
57    return factory.CreateStorage(config.Type)
58}
59```
60</pattern>
61 
62## Configuration with Defaults
63 
64<requirement type="always">
65**Always provide defaults:**
66</requirement>
67 
68<pattern type="configuration_defaults">
69```go
70func NewService(config *Config) *Service {
71    if config == nil {
72        config = DefaultConfig() // Always provide defaults
73    }
74    return &Service{config: config}
75}
76```
77</pattern>
78 
79<pattern type="configuration_implementation">
80```go
81// ✅ Good: Centralized configuration with defaults
82type ServiceConfig struct {
83    Port        int           `yaml:"port"`
84    Timeout     time.Duration `yaml:"timeout"`
85    MaxRetries  int           `yaml:"max_retries"`
86}
87 
88func DefaultServiceConfig() *ServiceConfig {
89    return &ServiceConfig{
90        Port:       8080,
91        Timeout:    30 * time.Second,
92        MaxRetries: 3,
93    }
94}
95 
96func NewServiceFromConfig(cfg *ServiceConfig) *Service {
97    if cfg == nil {
98        cfg = DefaultServiceConfig()
99    }
100    return &Service{config: cfg}
101}
102```
103</pattern>
104 
105## Graceful Shutdown
106 
107<requirement type="long_running_services">
108**REQUIRED for long-running services:**
109</requirement>
110 
111<pattern type="graceful_shutdown">
112```go
113quit := make(chan os.Signal, 1)
114signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
115select {
116case <-ctx.Done():
117    return shutdown(ctx)
118case <-quit:
119    return shutdown(ctx)
120}
121```
122</pattern>
123 
124## Middleware Pattern
125 
126<context type="http_handlers">
127**For HTTP handlers:**
128</context>
129 
130<pattern type="middleware_implementation">
131```go
132func authMiddleware() gin.HandlerFunc {
133    return func(c *gin.Context) {
134        if !isValidToken(c.GetHeader("Authorization")) {
135            c.JSON(401, gin.H{"error": "unauthorized"})
136            c.Abort()
137            return
138        }
139        c.Next()
140    }
141}
142```
143</pattern>
144 
145## Resource Management
146 
147<context type="connection_handling">
148**Connection limits and cleanup:**
149</context>
150 
151<pattern type="resource_management">
152```go
153// Connection limits
154if len(m.clients) >= m.config.MaxConnections {
155    return fmt.Errorf("max connections reached")
156}
157 
158// Cleanup with defer
159defer func() {
160    m.cancel()
161    m.wg.Wait()
162    if closeErr := m.conn.Close(); closeErr != nil {
163        log.Error("failed to close connection", "error", closeErr)
164    }
165}()
166```
167</pattern>
168 
169## Interface Design (ISP Implementation)
170 
171<guideline type="interface_size">
172**Small, focused interfaces (ISP):**
173</guideline>
174 
175<pattern type="interface_segregation">
176```go
177// ✅ Good: Small, focused interfaces
178type Reader interface {
179    Read(ctx context.Context, id core.ID) (*Data, error)
180}
181 
182type Writer interface {
183    Write(ctx context.Context, data *Data) error
184}
185 
186type Deleter interface {
187    Delete(ctx context.Context, id core.ID) error
188}
189 
190// Compose when needed
191type Repository interface {
192    Reader
193    Writer
194    Deleter
195}
196 
197// ❌ Bad: Monolithic interface
198type DataManager interface {
199    Read(ctx context.Context, id core.ID) (*Data, error)
200    Write(ctx context.Context, data *Data) error
201    Delete(ctx context.Context, id core.ID) error
202    Backup(ctx context.Context) error
203    Restore(ctx context.Context) error
204    Migrate(ctx context.Context) error
205}
206```
207</pattern>
208 
209<pattern type="interface_definition">
210```go
211// Small, focused interfaces for specific domains
212type Storage interface {
213    SaveMCP(ctx context.Context, def *MCPDefinition) error
214    LoadMCP(ctx context.Context, name string) (*MCPDefinition, error)
215    Close() error
216}
217```
218</pattern>
219 
220<best_practices type="interface_organization">
221**Interface best practices:**
222- Define interfaces in separate files when used across packages
223- Keep interfaces small and focused on specific behavior
224- Use interface composition for complex behavior
225- Honor contracts consistently (LSP)
226</best_practices>
227 
228## Constructor Patterns (DIP Implementation)
229 
230<requirement type="mandatory">
231**MANDATORY for all services:**
232</requirement>
233 
234<pattern type="dependency_injection">
235```go
236// ✅ Good: Depends on abstraction (DIP)
237type WorkflowService struct {
238    taskRepo TaskRepository // interface
239    executor TaskExecutor  // interface
240}
241 
242func NewWorkflowService(taskRepo TaskRepository, executor TaskExecutor) *WorkflowService {
243    return &WorkflowService{
244        taskRepo: taskRepo,
245        executor: executor,
246    }
247}
248 
249// ❌ Bad: Depends on concrete implementation
250type WorkflowService struct {
251    taskRepo *PostgreSQLTaskRepository // concrete
252    executor *DockerExecutor          // concrete
253}
254```
255</pattern>
256 
257<pattern type="service_constructor">
258```go
259// ✅ Required pattern for all services
260type AgentService struct {
261    repo   AgentRepository
262    config *AgentConfig
263}
264 
265func NewAgentService(
266    repo AgentRepository,
267    config *AgentConfig,
268) *AgentService {
269    if config == nil {
270        config = DefaultAgentConfig()
271    }
272    return &AgentService{
273        repo:   repo,
274        config: config,
275    }
276}
277```
278</pattern>
279 
280## Single Responsibility Examples (SRP Implementation)
281 
282<pattern type="srp_separation">
283```go
284// ✅ Good: Single responsibility
285type UserValidator struct{}
286func (v *UserValidator) ValidateEmail(email string) error { /* validation logic */ }
287 
288type UserRepository struct{}
289func (r *UserRepository) SaveUser(ctx context.Context, user *User) error { /* persistence logic */ }
290 
291// ❌ Bad: Multiple responsibilities
292type UserService struct{}
293func (s *UserService) ValidateAndSaveUser(ctx context.Context, email string) error {
294    // validation + persistence mixed
295}
296```
297</pattern>
298 
299## Context Handling Patterns
300 
301<requirement type="mandatory">
302**Context as first parameter:**
303</requirement>
304 
305<pattern type="context_propagation">
306```go
307// ✅ Context as first parameter
308func (s *TaskService) ExecuteTask(ctx context.Context, task *core.Task) (*core.TaskResult, error) {
309    select {
310    case <-ctx.Done():
311        return nil, ctx.Err()
312    default:
313        return s.doExecuteTask(ctx, task)
314    }
315}
316```
317</pattern>
318 
319## Resource Management Patterns
320 
321<pattern type="resource_cleanup">
322```go
323// ✅ Proper resource cleanup
324func (s *Service) ProcessWithResources(ctx context.Context) error {
325    conn, err := s.acquireConnection()
326    if err != nil {
327        return fmt.Errorf("failed to acquire connection: %w", err)
328    }
329    defer func() {
330        if closeErr := conn.Close(); closeErr != nil {
331            log.Error("failed to close connection", "error", closeErr)
332        }
333    }()
334    return s.processWithConnection(ctx, conn)
335}
336 
337// ✅ Timeout handling with cleanup
338func (s *Service) ProcessWithTimeout(ctx context.Context, timeout time.Duration) error {
339    ctx, cancel := context.WithTimeout(ctx, timeout)
340    defer cancel() // Always cancel to free resources
341    done := make(chan error, 1)
342    go func() {
343        done <- s.heavyProcessing(ctx)
344    }()
345    select {
346    case err := <-done:
347        return err
348    case <-ctx.Done():
349        return fmt.Errorf("operation timed out: %w", ctx.Err())
350    }
351}
352 
353// ✅ Multiple resource cleanup
354func (s *Service) ProcessMultipleResources(ctx context.Context) error {
355    file, err := os.Open("data.txt")
356    if err != nil {
357        return fmt.Errorf("failed to open file: %w", err)
358    }
359    defer file.Close()
360    lock := s.mutex.Lock()
361    defer s.mutex.Unlock()
362    return s.processFileWithLock(ctx, file)
363}
364```
365</pattern>
366