HTTP Server Initialization

Relevant source files

The following files were used as context for generating this wiki page:

• src/main.ts
• src/http-server.ts
• src/slack/client.ts
• deploy/cloudformation.yml
• entrypoint.sh
• src/log.ts

The HTTP server in pi-digby serves as a lightweight service responsible for handling health checks and external webhooks. It is a critical component for deployment in containerized environments like AWS ECS, where it facilitates health monitoring and enables integration with external services like Linear via dedicated webhook endpoints.

The server operates alongside the primary Slack Socket Mode client, providing a synchronous entry point for HTTP-based traffic while the main bot logic processes asynchronous events from Slack. Sources: src/main.ts:241-243, src/http-server.ts:1-12

Server Architecture and Lifecycle

The HTTP server is encapsulated within the HttpServer class. It utilizes the Node.js native http module to create a server instance that listens for incoming requests. The initialization process begins in the application entry point where the server is instantiated and started before other primary services like the Slack client. Sources: src/http-server.ts:18, src/main.ts:242-243

Initialization Flow

The following diagram illustrates the sequence of events during the HTTP server startup and its registration in the main application.

Routing Logic

The server implements a basic router that differentiates between health checks, registered webhooks, and unsupported paths.

Health Checks

The server responds to GET requests on / and /health with a 200 OK status and the text "ok". This is primarily used by the AWS ECS agent to verify the container's availability. Sources: src/http-server.ts:55-59, deploy/cloudformation.yml:584-590

Webhook Handling

Webhooks are handled via POST requests under the /webhooks/ path.

• Registration: Handlers are registered using registerWebhook(path, handler).
• Validation: If a request is made to a webhook path using a method other than POST, the server returns a 405 Method Not Allowed.
• Execution: If a handler is registered for the path, it is executed. If no handler exists, the server returns a 404 Not Found to ensure upstream senders (like Linear) do not assume successful delivery. Sources: src/http-server.ts:21-47

Request Dispatch Flow

Configuration and Deployment

The HTTP server defaults to port 8080. This configuration is aligned with the container health check settings defined in the infrastructure deployment files. Sources: src/http-server.ts:28, deploy/cloudformation.yml:586

Parameter	Default Value	Usage
Port	8080	Port the server listens on inside the container.
Health Check Path	/health	Endpoint polled by ECS to determine container health.
Linear Webhook	/webhooks/linear	Endpoint for Linear service integrations.

Sources: src/http-server.ts:13-14, 28, src/main.ts:294, deploy/cloudformation.yml:586

Environment Integration

During the container startup via entrypoint.sh, environment variables such as EXA_API_KEY are processed, and the application is eventually executed. The HTTP server is started as part of the node dist/main.js command. The server ensures observability by logging registration events and listening status to the console. Sources: entrypoint.sh:51, src/http-server.ts:23, 64, src/log.ts:1-11

Error Handling

The server includes internal protections to prevent the application from crashing due to HTTP layer issues:

1. Handler Exceptions: If a registered webhook handler throws an error, it is caught, logged as a warning, and an 500 Internal Server Error is returned to the client (if headers haven't been sent).
2. Server Errors: The underlying server instance listens for 'error' events to log issues like port conflicts without terminating the process.
3. Unregistered Routes: Non-matching paths explicitly return 404 Not Found.

Sources: src/http-server.ts:46-51, 67-69

Conclusion

HTTP Server Initialization in pi-digby provides the necessary infrastructure for external visibility and health monitoring. By prioritizing explicit 404 responses for missing webhooks and maintaining a simple routing logic for health checks, the system ensures reliable operation within AWS ECS while allowing for extensible integration with third-party webhooks.