Implement AsyncAPI specification and event-driven architecture

[davideme]

Description

Add AsyncAPI specification and event-driven architecture support to the lamp control API reference implementations.

Motivation

AsyncAPI is a widely adopted specification for describing event-driven APIs, similar to how OpenAPI describes REST APIs. Adding AsyncAPI support would:

• Demonstrate modern event-driven API patterns alongside existing REST/GraphQL/gRPC implementations
• Provide a complete reference for asynchronous communication patterns
• Show how to implement webhooks, message queues, and real-time updates
• Complement the existing synchronous API implementations

Proposed Implementation

AsyncAPI Specification

• Create AsyncAPI 3.0 specification document for lamp control events
• Define event schemas for lamp state changes (lamp.turned_on, lamp.turned_off, lamp.brightness_changed)
• Document channels, operations, and message formats
• Add AsyncAPI documentation generation

Event-Driven Features

• Implement event publishing when lamp state changes
• Add support for real-time lamp status subscriptions
• Create event consumers/subscribers for each language implementation
• Add message broker integration (Redis Streams, Apache Kafka, RabbitMQ)

Language Implementations

Add AsyncAPI support to each existing language:

• TypeScript/Node.js: WebSocket, Server-Sent Events, message queues
• Python: AsyncIO, WebSockets, Celery/Redis integration
• Java: Spring WebFlux, reactive streams, Kafka integration
• PHP: ReactPHP, Ratchet WebSocket server
• Ruby: ActionCable, async gems
• Go: Goroutines, channels, WebSocket support

Documentation

• Add AsyncAPI documentation to main README
• Create event-driven architecture guide
• Document real-time integration patterns
• Add examples for different messaging patterns (pub/sub, request/reply)

Testing

• Add integration tests for event publishing/consuming
• Test real-time WebSocket connections
• Validate AsyncAPI specification compliance
• Add load testing for concurrent connections

Acceptance Criteria

• AsyncAPI 3.0 specification document is created and valid
• Each language implementation supports event publishing and consuming
• Real-time lamp status updates work via WebSockets/SSE
• Message broker integration is documented and tested
• Documentation includes clear examples and integration guides
• All tests pass including new async/event-driven tests

Additional Notes

This implementation should maintain consistency with the existing project structure and follow the same quality standards as REST/GraphQL/gRPC implementations.

Consider using tools like:

• AsyncAPI Generator for code generation
• AsyncAPI Studio for specification editing
• WebSocket testing tools for validation