Add parallel HTTPS server support

[heavyrubberslave]

When SSL_KEY and SSL_CERT env vars point to valid certificate files, an HTTPS server starts alongside the always-on HTTP server on HTTPS_PORT (default 1338). Socket.IO attaches to both servers via ServerServiceProvider.

Summary by CodeRabbit

• New Features

  • Optional HTTPS support with configurable SSL certificates and a dedicated HTTPS port.
  • Specialized error handling for async interval timeout scenarios.

• Refactor

  • Server startup split to support separate HTTP/HTTPS listeners; CORS origin handling centralized into shared configuration.

• Chores

  • Updated configuration documentation with HTTPS setup placeholders.

[coderabbitai]

Too much diff to scan? Review this PR in Change Stack to start with the highest-impact changes.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8815a67e-884d-44a3-a2ef-5f02936a1ede

📥 Commits

Reviewing files that changed from the base of the PR and between 47c4376 and 6684517.

📒 Files selected for processing (3)

• src/index.ts
• src/serviceMap.ts
• src/serviceProvider/serverServiceProvider.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/index.ts

---

📝 Walkthrough

Walkthrough

Adds optional HTTPS server support with environment-driven SSL configuration, shared CORS options, and conditional Socket.IO attachment; also introduces a typed IntervalTimeoutError and special-cases it in error logging.

Changes

HTTPS Server Support

Layer / File(s)	Summary
Env, CORS, and entry wiring .env.example, src/index.ts	Adds commented SSL vars and HTTPS port to .env.example. src/index.ts parses APP_HTTP_PORT/APP_HTTPS_PORT, builds corsOptions from ALLOWED_ORIGINS, derives sslConfig from SSL_KEY/SSL_CERT, and registers ServerServiceProvider(app, corsOptions, sslConfig).
Service registry and provider wiring src/serviceMap.ts, src/serviceProvider/serverServiceProvider.ts	ServiceMap gains server.http and server.https types. ServerServiceProvider now accepts (app, corsOptions, sslConfig?), creates an HTTP server from the Express app, instantiates Socket.IO with injected CORS, attaches it to HTTP, and conditionally creates/attaches an HTTPS server when SSL files load successfully.

Interval Timeout Error Handling

Layer / File(s)	Summary
IntervalTimeoutError definition and usage src/util/async.ts, src/util/error.ts	Exports IntervalTimeoutError class; setIntervalAsync rejects timeouts with this typed error; logError imports and early-handles IntervalTimeoutError by logging a warning and returning without normalizing to BaseError.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I nibbled keys and certs in the night,
Two ports now listen, one plain, one tight,
Socket threads hop where secure lanes appear,
Timeouts named kindly so logs stay clear,
A rabbit cheers the server's new light.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add parallel HTTPS server support' directly and clearly describes the main change: enabling an HTTPS server to run alongside the existing HTTP server when SSL certificates are provided.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/https-support

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/index.ts (1)

181-185: ⚖️ Poor tradeoff

Consider adding error handling for listen failures.

While Node.js will throw by default if the port is unavailable, explicitly handling listen errors would provide better diagnostics and graceful degradation.

♻️ Optional improvement to add error handler

 if (httpsServer !== undefined) {
-    httpsServer.listen(APP_HTTPS_PORT, () => {
+    httpsServer.listen(APP_HTTPS_PORT, () => {
         logger.info(`SlvCtrl+ server listening on https://localhost:${APP_HTTPS_PORT} (ssl)`);
+    }).on('error', (err: Error) => {
+        logger.error(`HTTPS server failed to start: ${err.message}`, err);
     });
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/index.ts` around lines 181 - 185, The httpsServer.listen call lacks an
explicit 'error' handler for startup failures; attach a listener on httpsServer
for the 'error' event (or pass an error-first callback to listen) to catch bind
errors and log them via logger.error including APP_HTTPS_PORT and the error, and
optionally perform graceful shutdown/exit; update the block around
httpsServer.listen/httpsServer to add this error handling referencing
httpsServer, listen, APP_HTTPS_PORT, and logger.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/index.ts`:
- Around line 49-51: The current creation of httpsServer uses
fs.readFileSync(SSL_KEY_FILE) and fs.readFileSync(SSL_CERT_FILE) directly which
can throw and crash startup; wrap the file reads in a try-catch around the
https.createServer call (or a small helper) so that if reading SSL_KEY_FILE or
SSL_CERT_FILE fails you log a clear error (including the file path and error
message) via your logger and either fallback to undefined for httpsServer or
call process.exit(1); update the code that constructs httpsServer (the
https.createServer(...) invocation and any surrounding logic referencing
SSL_KEY_FILE/SSL_CERT_FILE) to use the try-catch and safe behavior.

In `@src/serviceProvider/serverServiceProvider.ts`:
- Around line 18-23: The Socket.IO server is configured with origin: '*' which
bypasses ALLOWED_ORIGINS; update the Server(...) CORS option in the socket
initialization (the Server constructor call) to use the same origin callback
logic as Express (e.g., a corsOriginCallback function that checks
ALLOWED_ORIGINS.includes(origin) and allows undefined/or empty list), and ensure
ALLOWED_ORIGINS or that corsOriginCallback is passed into or imported by
serverServiceProvider so the Server CORS uses the shared corsOriginCallback
instead of '*' to enforce the same origin restrictions.

---

Nitpick comments:
In `@src/index.ts`:
- Around line 181-185: The httpsServer.listen call lacks an explicit 'error'
handler for startup failures; attach a listener on httpsServer for the 'error'
event (or pass an error-first callback to listen) to catch bind errors and log
them via logger.error including APP_HTTPS_PORT and the error, and optionally
perform graceful shutdown/exit; update the block around
httpsServer.listen/httpsServer to add this error handling referencing
httpsServer, listen, APP_HTTPS_PORT, and logger.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 985b4539-646b-4502-b1c2-7cd520adebd4

📥 Commits

Reviewing files that changed from the base of the PR and between 81dc622 and 47c4376.

📒 Files selected for processing (5)

• .env.example
• src/index.ts
• src/serviceProvider/serverServiceProvider.ts
• src/util/async.ts
• src/util/error.ts

[heavyrubberslave]

@coderabbitai rate limit

[coderabbitai]

Your plan includes 1 PR review per hour. More reviews will be available in 2 minutes and 34 seconds.

[heavyrubberslave]

@coderabbitai review please

[coderabbitai]

@heavyrubberslave Sure! I'll start reviewing the PR right away.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.