Skip to content

feat(logging): report transport failures that were silent or verbose-only - #27

Merged
Mikhus merged 1 commit into
masterfrom
logging
Aug 20, 2026
Merged

feat(logging): report transport failures that were silent or verbose-only#27
Mikhus merged 1 commit into
masterfrom
logging

Conversation

@creomobile

@creomobile creomobile commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Reports transport failures that previously left no trace at all, or only with IMQOptions.verbose enabled — which production does not enable. Every line goes through the configured logger and is written whether or not verbose is set, in line with the documented intent of IMQOptions.verbose: connection lifecycle messages and internal errors are always written.

What is now reported:

  • a write to Redis rejected inside send(), as a failure episode: the first rejection names the queue, the operation, the message id and a code, further rejections are counted, and the first successful write reports the recovery with that count. The caller already holds the message id and gets no rejection, so this was observable only through the optional errorHandler, which most callers do not pass;
  • safe reading of a queue ending on anything other than a planned stop, reconnect or destroy — a planned stop stays quiet, as before;
  • a subscription being established and being restored after a reconnect, plus a failed reconnection attempt: the absence of the restore line after a reconnect is what makes a lost subscription provable;
  • safe-delivery maintenance disabling itself for good when the writer connection is gone;
  • a silent failure of the periodic watcher-existence check (the failures of delayed-message processing and of watcher initialization were already logged and are not duplicated);
  • messages of expired worker leases being re-queued, aggregated into one line per destination queue per pass with a count, and a worker key that could not be deleted: the two causes of a duplicate delivery;
  • keys removed by the built-in cleanup, with the number of candidates and the number actually deleted — a destructive action which left no trace before;
  • a publish whose channel has no subscribers, on entering that state, and, in a clustered queue, a publish with no server to publish to at all, round-robin having no available instance left, and a joining server failing to start or to subscribe.

A failure reason is never taken from the error as it is: only an allow-listed code is printed — an IMQ_-prefixed framework code, a system E… code, a small integer, a known Redis reply code (WRONGTYPE, NOSCRIPT, LOADING, …) or one of a few known Redis-client failure messages mapped to codes of our own. Everything else, including the error's message, stack and class name, is reported as unknown. No line ever carries a message payload, call arguments or a raw Redis key.

No control flow, return value, Redis command, round-trip or timer was changed, and no new public API was added — the change is diagnostics only, and a logger which throws cannot influence queue behaviour. One deliberate difference: the line about a worker key that could not be deleted is now written through a contained writer, so a throwing logger can no longer surface there as an unhandled rejection.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Refactor / internal
  • Other:

Checklist

  • I have read the Contributing guide.
  • Tests added or updated, and the full suite passes locally (npm test).
  • Docs / doc-blocks updated where relevant.
  • The PR is focused on a single logical change.

Contribution terms (required)

  • I have read and agree to the @imqueue Contribution Terms.
    I grant the project owner the right to license my contribution
    commercially, royalty-free, my contribution stays available under
    GPL-3.0, I keep my copyright, and I understand I will receive no fee for
    it. If I did not agree, I would not be submitting this contribution.

…ality

- Introduced a new logging helper in `src/helpers/logging.ts` that provides functionality to extract loggable failure codes from various error types.
- Updated `src/helpers/index.ts` to export the new logging helper.
- Enhanced unit tests in `test/unit/helpers/logging.spec.ts` to cover various scenarios for the `errorCode` function.
- Integrated logging functionality into `ClusteredRedisQueue` and `RedisQueue` classes, ensuring appropriate logging during instance selection, publishing, and error handling.
- Added tests to verify logging behavior in different failure scenarios across `ClusteredRedisQueue` and `RedisQueue`.
@github-actions

github-actions Bot commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

All contributors have signed the @imqueue Contribution Terms. ✅
Posted by the CLA Assistant Lite bot.

@creomobile
creomobile requested a review from Mikhus August 19, 2026 19:10
@creomobile creomobile changed the title feat(logging): add logging helper with error code extraction function… feat(logging): report transport failures that were silent or verbose-only Aug 19, 2026
@creomobile

Copy link
Copy Markdown
Contributor Author

I have read the CLA Document and I hereby sign the CLA

github-actions Bot added a commit that referenced this pull request Aug 19, 2026
@Mikhus
Mikhus merged commit 50d4247 into master Aug 20, 2026
11 of 20 checks passed
@Mikhus
Mikhus deleted the logging branch August 20, 2026 13:31
@github-actions github-actions Bot locked and limited conversation to collaborators Aug 20, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants