Options for connect() do not work as intended

[cb0s]

Observed behavior

Hi!
While working on a project with nats I noticed that something doesn't work as intended (or at least how I understand it). I wanted to use nats.connect() without reconnects on startup (try once and fail), however, I wasn't able to achieve it. My test code for that was more or less a mesh-up from different parts of the official python client documentation. Strangely enough, connect_timeout didn't seem to have an effect either, only error_cb did (I was able to get notified on connection errors). The following code should reproduce this behaviour:

import nats
import asyncio

async def main():
    connecting_options = {
        "allow_reconnect": False,       # only try to connect once
        "max_reconnect_attempts": 0,    # test
        "connect_timeout": 1,           # fail after 1 sec.
    }
    nc = await nats.connect(servers="localhost:4222", **connecting_options)
    await nc.close()

if __name__ == "__main__":
    asyncio.run(main())

I hope you will be able to help me or at least point me to the right direction. I also noticed that the documentation on these parameters is sparse (#600 seems to try to fix that though), but I feel that after reading this and this and manually inspecting the source code, the code above should fail after 1 second. If I misunderstood anything, please let me know :)

Expected behavior

I want the code to throw an unhandled exception which can be handled manually, later. Additionally I expect the code to take only 1 sec to fail instead of the default 2 sec.

This all can be useful to notify a testing client about the failed connection attempt for instance.

Server and client version

nats-server is not available as the client is intended to fail
pip show nats-py shows: Version: 2.9.0

Host environment

Running on Windows 10 Host in WSL - Ubuntu 24.04 - Python 3.12.

Steps to reproduce

See script above with the specified dependencies.

[caspervonb]

• So for the connect_timeout, this is the for the transport layer, this helps against things like:
  • Unresponsive servers
  • Network issues causing slow TCP connection establishment
  • Slow TLS handshakes
  • Slow initial NATS protocol handshake.

It is not an absolute timeout for the connect call.

• We probably want a separate flag for initial reconnection, e.g see Missing option to control initial connection behavior #663. Did a draft but need another pass, got messy.

• Based on usage, max_reconnect_attempts isn't actually allowed to be 0, set it to 1. But this isn't enforced at runtime.