goplt/docs/content/stories/epic2/AUDIT_SERVICE_SUMMARY.md

Audit Service Implementation Summary

Overview

The Audit Service has been successfully implemented as an independent microservice. It provides audit logging functionality with gRPC API, database persistence, and service registry integration.

Completed Components

1. Service Implementation (services/audit/internal/service/audit_service.go)

• AuditService: Core business logic for audit logging
• Record: Records audit log entries to database
• Query: Queries audit logs with filters (user_id, action, resource, time range, pagination)
• Uses Ent ORM for database operations
• Supports metadata as JSON

2. gRPC Server Implementation (cmd/audit-service/audit_service_fx.go)

• auditServerImpl: Implements AuditService gRPC interface
• Record RPC: Records audit log entries
• Query RPC: Queries audit logs with filters
• Converts between proto types and service types
• Error handling with proper gRPC status codes

3. Service Entry Point (cmd/audit-service/main.go)

• Independent service entry point
• Dependency injection using uber-go/fx
• Database connection with schema isolation (audit schema)
• Automatic migrations on startup
• Health check registry with database checker
• gRPC server lifecycle management
• Service registry registration (Consul)
• Graceful shutdown handling

4. Database Schema (internal/ent/schema/audit_log.go)

• AuditLog entity with fields:
  • id: Unique identifier
  • user_id: ID of the user/actor
  • action: Action performed (e.g., "user.create")
  • resource: Resource type (e.g., "user", "role")
  • resource_id: ID of the target resource
  • ip_address: Client IP address
  • user_agent: Client user agent
  • metadata: Additional metadata as JSON
  • timestamp: When the action occurred
• Indexes on: user_id, resource_id, timestamp, action, resource

5. Configuration (config/default.yaml)

• Added service configuration:

  services:
    audit:
      port: 8084
      host: "localhost"
  

Architecture

The Audit Service follows the microservices architecture pattern:

• Independent Deployment: Has its own entry point (cmd/audit-service/main.go)
• Schema Isolation: Uses audit database schema
• Service Discovery: Registers with Consul service registry
• gRPC API: Exposes gRPC server on port 8084 (configurable)
• Health Checks: Implements gRPC health check protocol
• Reflection: Enabled for grpcurl testing

Files Created

1. services/audit/internal/service/audit_service.go - Service business logic
2. services/audit/internal/api/server.go - gRPC server implementation (for reference, actual implementation in cmd)
3. services/audit/internal/api/grpc_server.go - gRPC server wrapper (for reference)
4. cmd/audit-service/main.go - Service entry point
5. cmd/audit-service/audit_service_fx.go - FX providers for service creation
6. services/audit/service.go - Public API package (placeholder)

Testing the Audit Service

Prerequisites

1. PostgreSQL running and accessible
2. Consul running (optional, for service discovery)
3. Configuration set up in config/default.yaml

Start the Service

# Using nix-shell (recommended)
nix-shell
go run ./cmd/audit-service/main.go

# Or build and run
go build -o bin/audit-service ./cmd/audit-service
./bin/audit-service

Verify Service Startup

The service should:

1. Connect to database
2. Create audit schema if it doesn't exist
3. Run migrations (create audit_logs table)
4. Start gRPC server on port 8084
5. Register with Consul (if available)

Check logs for:

• "Database migrations completed for audit service"
• "Starting Audit Service gRPC server"
• "Audit Service gRPC server started successfully"
• "Registered Audit Service with service registry"

Test with grpcurl

# List available services
grpcurl -plaintext localhost:8084 list

# Check health
grpcurl -plaintext localhost:8084 grpc.health.v1.Health/Check

# Record an audit log entry
grpcurl -plaintext -d '{
  "entry": {
    "user_id": "user-123",
    "action": "user.login",
    "resource": "user",
    "resource_id": "user-123",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0",
    "metadata": {
      "method": "POST",
      "endpoint": "/api/v1/auth/login"
    },
    "timestamp": 1699123456
  }
}' localhost:8084 audit.v1.AuditService/Record

# Query audit logs
grpcurl -plaintext -d '{
  "user_id": "user-123",
  "limit": 10,
  "offset": 0
}' localhost:8084 audit.v1.AuditService/Query

Verify Database

# Connect to database
docker exec -it goplt-postgres psql -U goplt -d goplt

# Switch to audit schema
SET search_path TO audit;

# Check table exists
\dt

# Query audit logs
SELECT * FROM audit_logs ORDER BY timestamp DESC LIMIT 10;

Next Steps

The Audit Service is complete and ready for use. Other services (Auth, Identity, Authz) can use the Audit Service via the AuditServiceClient interface to record audit events.

Notes

• The service uses inline implementation in cmd/audit-service/audit_service_fx.go to avoid importing internal packages from cmd
• The internal service implementation in services/audit/internal/service/ exists for reference and can be used by other internal packages
• Service registry registration happens on startup; deregistration on shutdown (service ID stored for proper cleanup)
• Health checks are available via gRPC health protocol