How andy-blum/ddev-websocket works
Project Type and Purpose
• This is an open-source add-on for DDEV (local Docker-based PHP/dev environment) that provides a simple, extensible WebSocket server.
• Key use case: enable bi-directional, real-time communication between browser clients and server without page refresh.
• It’s packaged as a Docker-service sidecar within a DDEV project, customizable via JavaScript “plugins.”
File Structure Analysis
• Top-level directories:
– .github/: CI workflows (tests.yml), issue and PR templates
– js/: client helper (SocketClient.js) and plugin stubs
– nginx/: custom nginx configuration for WebSocket proxying
– web-build/: Dockerfile and server entrypoint (SocketServer.js)
– tests/: Bats tests and test data
• Key config files:
– config.websocket.yml & install.yaml: DDEV add-on definitions
– nginx/ddev-websocket.conf: proxies incoming WebSocket traffic to the Node.js server
• Build/deploy artifacts:
– web-build/Dockerfile builds the Node.js WebSocket server image
README Insights
• Describes plugin interface (onConnection, onMessage, onError, onClose).
• Usage pattern: browser WebSocket → wss://<project>.ddev.site:8080 → server.
• Dependencies: Node.js, ws package, DDEV CLI.
• Developer hooks: drop .js files into .ddev/js/plugins; logs via ddev logs -s websocket.
Components
a. Main Components
– Browser Client: Web pages or console scripts using native WebSocket API or js/SocketClient.js.
– DDEV Network & Reverse Proxy: Docker network, nginx proxy forwarding wss:// calls to container.
– WebSocket Server Container: Node.js app (SocketServer.js) built via web-build/Dockerfile.
– Plugin Loader & Modules: dynamic loader that requires each plugin in .ddev/js/plugins.
– DDEV CLI / Add-on Framework: install.yaml triggers service startup; config.websocket.yml configures port, image.
– Logging & Testing: DDEV logging subsystem; tests directory for automated Bats tests.
b. Relationships and Data Flow
1. Browser issues wss://…:8080 → hits nginx in DDEV web container.
2. nginx proxy forwards → WebSocket Server Container on internal port.
3. Server accepts connection → Plugin Loader attaches event handlers.
4. onMessage events → dispatched to each plugin’s onMessage handler → plugin may call this.send().
5. Responses flow back along the same socket → Browser.
6. CLI commands (ddev logs, ddev restart) manage service lifecycle and surface logs.
c. Architectural Patterns
– Plugin Pattern: runtime loading of modules implementing optional hooks.
– Event-Driven: Node.js event loop with ws’s connection/message/error/close events.
– Sidecar Service: runs alongside the main web container, integrated via DDEV network and configuration.
d. Key Technologies
– Node.js & ws package (WebSocketServer)
– Docker & Dockerfile (web-build/)
– nginx (proxy configuration for DDEV)
– DDEV add-on YAML files (install.yaml, config.websocket.yml)
– JavaScript plugin API