feat: add opt-in automatic recovery for promise and callback APIs

[ShiriNmi1520]

Summary

This PR adds a generic, opt-in recovery mechanism to amqplib for both public APIs:

• Promise API (require('amqplib'))
• Callback API (require('amqplib/callback_api'))

Recovery is enabled only when connect(..., { recovery: ... }) is provided, so the default behaviour remains unchanged.

Motivation

Fix #25

What changed

• Added shared recovery engine: lib/recovery.js
• Wired recovery into:
  • channel_api.js
  • callback_api.js
• Added docs in README.md for usage/options/events
• Added unit tests in test/recovery.js

Recovery options

• initialDelay
• maxDelay
• factor
• jitter
• maxRetries (also accepts maxAttempts)
• setup(model, client[, done]) called after each successful connect/reconnect

Mermaid sequence chart

sequenceDiagram
    autonumber
    participant App
    participant Client as amqplib (recovering client)
    participant Broker as RabbitMQ

    App->>Client: connect(url, { recovery })
    Client->>Broker: open TCP + AMQP handshake
    Broker-->>Client: open-ok
    Client->>Client: run recovery.setup(...)
    Client-->>App: emit "connect"

    Note over Broker,Client: normal operation

    Broker-x Client: socket/connection closed
    Client-->>App: emit "disconnect"
    Client-->>App: emit "reconnectScheduled"

    loop retry with backoff+jitter
        Client->>Broker: reconnect + handshake
        alt success
            Broker-->>Client: open-ok
            Client->>Client: run recovery.setup(...)
            Client-->>App: emit "connect"
        else failed and retries remain
            Client-->>App: emit "connectFailed"
            Client-->>App: emit "reconnectScheduled"
        end
    end

    alt retries exhausted
        Client-->>App: emit "reconnectFailed"
    end

Loading

Backward compatibility

• No behavior change unless recovery is explicitly configured.

Notes / limitations

• This provides connection-level recovery and setup replay.
• It does not guarantee transparent replay of in-flight channel operations across disconnects.

[cressie176]

Thank you for this @ShiriNmi1520, it looks like a very comprehensive piece of work. I've have some time off next week and will review.

[cressie176]

@ShiriNmi1520, thank you for your patience. It is a really good PR. Just have a lot on at the moment, so taking time to get to it.

[cressie176]

@ShiriNmi1520 I've finished my review now. I have a few questions which I suspect will lead to some changes. I also wanted to add that this is some of most well written code I have ever seen. Very well crafted. Thank you.

[ShiriNmi1520]

@ShiriNmi1520 I've finished my review now. I have a few questions which I suspect will lead to some changes. I also wanted to add that this is some of most well written code I have ever seen. Very well crafted. Thank you.

Appreciate your review, please allow me some time to implement modifications based on your review :)

[ShiriNmi1520]

Thank you again for taking the time to review everything so carefully. Each of your points was helpful and made a difference. I've pushed five follow-up commits, with each one addressing a separate change.

[cressie176]

My bad re unref - adding it broke the recovery tests in Node 18, 20 and 22. Thinking about it, we didn't want to unref the timer between recovery attempts, as if the event loop was drained it would have caused the application to exit. You already clear the timer when close is called, so the user can still exit the application gracefully.

[cressie176]

Published as amqplib v1.1.0. Thank you very much