# Story 4.10: Pluggable Audit Storage Interface

## Status: Planned

## Priority: High

## Estimated Effort: Medium (2-3 days)

## Dependencies: None

## Epic / Series

Part of Epic 4: Enterprise Compliance & Observability / Series 4.x

---

## Context / Background

Compliance-focused platform engineers need a pluggable audit storage interface with a simple file backend in core. This enables routing audit trails to enterprise stores (DB/cloud/SIEM) without modifying core.

---

## User Story

**As a** compliance-focused platform engineer  
**I want** a pluggable audit storage interface with a simple file backend in core  
**So that** I can route audit trails to enterprise stores (DB/cloud/SIEM) without modifying core

---

## Scope (In / Out)

### In Scope

- Define `StorageBackend` Protocol with async methods
- Implement `FileStorageBackend` in core (refactor existing behavior)
- `AuditTrail` accepts optional backend instance
- Default to file backend when not provided
- No breaking changes to public API
- Clear extension guidance

### Out of Scope

- Implementing enterprise backends (DB/cloud/SIEM) - these are plugins/extras
- Migration tools for existing audit logs
- Real-time replication

---

## Acceptance Criteria

### AC1: Protocol Definition

- [ ] Define `StorageBackend` Protocol:
  ```python
  class StorageBackend(Protocol):
      async def write(self, event: AuditEvent) -> None: ...
      async def flush(self) -> None: ...
      async def close(self) -> None: ...
  ```
- [ ] Protocol is documented and type-checkable

### AC2: File Backend Implementation

- [ ] Implement `FileStorageBackend` in core
- [ ] Refactor existing file storage to use backend
- [ ] Backend appends JSONL to daily files (existing behavior)
- [ ] Backend handles file rotation
- [ ] Backend is thread-safe

### AC3: AuditTrail Integration

- [ ] `AuditTrail` accepts optional backend instance
- [ ] Defaults to `FileStorageBackend` when not provided
- [ ] No breaking change to public `audit_*` helpers
- [ ] No breaking change to `get_audit_trail()`
- [ ] New params for backend injection

### AC4: Extension Guidance

- [ ] Document how to implement custom backends
- [ ] Provide example backend implementations
- [ ] Document backend lifecycle
- [ ] Document error handling expectations

---

## Technical Design / Implementation Notes

### Protocol Definition

Location: `src/fapilog/core/audit.py`

```python
from typing import Protocol

class StorageBackend(Protocol):
    """Protocol for audit event storage backends."""
    
    async def write(self, event: AuditEvent) -> None:
        """Write an audit event to storage."""
        ...
    
    async def flush(self) -> None:
        """Flush any buffered events."""
        ...
    
    async def close(self) -> None:
        """Close the storage backend."""
        ...
```

### File Backend Implementation

```python
class FileStorageBackend:
    """File-based storage backend for audit events."""
    
    def __init__(self, storage_path: Path):
        self.storage_path = storage_path
        self._lock = asyncio.Lock()
    
    async def write(self, event: AuditEvent) -> None:
        """Write event to daily JSONL file."""
        # Implementation
    
    async def flush(self) -> None:
        """Flush file buffers."""
        # Implementation
    
    async def close(self) -> None:
        """Close file handles."""
        # Implementation
```

### AuditTrail Refactoring

Modify `AuditTrail.__init__`:
```python
def __init__(
    self,
    policy: Optional[CompliancePolicy] = None,
    storage_path: Optional[Path] = None,
    backend: Optional[StorageBackend] = None,
) -> None:
    if backend is None:
        backend = FileStorageBackend(storage_path or Path("audit_logs"))
    self._backend = backend
```

---

## Tasks

### Phase 1: Protocol & Interface
- [ ] Define `StorageBackend` Protocol
- [ ] Document protocol requirements
- [ ] Add type hints

### Phase 2: File Backend
- [ ] Implement `FileStorageBackend`
- [ ] Refactor existing file storage code
- [ ] Ensure backward compatibility
- [ ] Add tests

### Phase 3: AuditTrail Integration
- [ ] Update `AuditTrail` to accept backend
- [ ] Update `_store_event()` to use backend
- [ ] Ensure default behavior unchanged
- [ ] Add tests

### Phase 4: Documentation
- [ ] Document protocol
- [ ] Document extension guide
- [ ] Provide example backends
- [ ] Update API docs

---

## Tests

### Unit Tests

- [ ] `FileStorageBackend` implements protocol
- [ ] File backend writes events correctly
- [ ] File backend handles file rotation
- [ ] `AuditTrail` with default backend (backward compatible)
- [ ] `AuditTrail` with custom backend

### Integration Tests

- [ ] Full audit trail with file backend
- [ ] Full audit trail with mock backend
- [ ] Backend lifecycle (write, flush, close)

---

## Documentation Updates

- [ ] Document `StorageBackend` Protocol
- [ ] Document extension guide
- [ ] Provide example backend implementations
- [ ] Update `AuditTrail` API docs

---

## Definition of Done

Story is complete when ALL of the following are true:

### Code Complete
- [ ] All acceptance criteria met and verified
- [ ] All tasks completed
- [ ] Code follows project style guide
- [ ] No linting errors or warnings
- [ ] Type checking passes (mypy strict)

### Quality Assurance
- [ ] Unit tests: >90% coverage of new code
- [ ] Integration tests: all scenarios passing
- [ ] Regression tests: no existing functionality broken
- [ ] Performance tests: no regression vs baseline
- [ ] Manual testing completed (if applicable)

### Documentation
- [ ] User-facing docs updated
- [ ] API reference updated (if applicable)
- [ ] Code examples added/updated
- [ ] CHANGELOG.md updated
- [ ] Inline code documentation complete

### Review & Release
- [ ] Code review approved
- [ ] Documentation reviewed for clarity
- [ ] CI/CD pipeline passing
- [ ] Ready for merge to main branch

### Backwards Compatibility
- [ ] No breaking changes OR breaking changes documented with migration guide
- [ ] Existing tests still pass
- [ ] Deprecation warnings added (if applicable)

---

## Risks / Rollback / Monitoring

### Risks

- **Risk:** Breaking changes to existing code
  - **Mitigation:** Default to file backend, maintain backward compatibility

- **Risk:** Protocol too restrictive
  - **Mitigation:** Keep protocol minimal, allow backend-specific extensions

### Rollback Plan

- Remove backend parameter
- Keep file backend as internal implementation
- No breaking changes if rolled back

---

## Related Documents

- [Audit Trail Documentation](../api-reference/audit-trail.md)
- [Story 4.11: Audit Integrity](./4.11.audit-integrity-hmac.md)

---

## Change Log

| Date       | Change                    | Author |
| ---------- | ------------------------- | ------ |
| 2025-01-10 | Initial story creation    | System |
