QServer maxSessions behavior in jPOS 3: Allowing multiple connections despite maxSessions=1

[chu-ngoc-hai]

Hi jPOS community,

I am migrating/running a project on jPOS 3 (using Q2), and I am facing an issue where the maxSessions configuration on org.jpos.q2.iso.QServer does not seem to restrict concurrent connections as expected.

Even though I configured maxSessions to 1, when a client connection is already established and active, a second connection (like telnet) can still connect successfully and reach ESTABLISHED state.

Here is my current QServer XML configuration:

<server name="my-iso-server" class="org.jpos.q2.iso.QServer" logger="my-logger">
    <attr name="port" type="java.lang.Integer">19806</attr> 
    <attr name="maxSessions" type="java.lang.Integer">1</attr> 
    <channel name="my-iso.channel" 
             class="org.jpos.iso.channel.ASCIIChannel"
             packager="my.company.packager.CustomPackager" logger="my-logger"> 
        <property name="keep-alive" value="true" />
        <property name="timeout" value="300000" />
    </channel>    
    <property name="ignore-iso-exceptions" value="true" />
    <request-listener
       class="my.company.processor.CustomRequestListener"
       logger="my-logger" realm="request-listener">
       <property name="request-processor" value="request-processor-custom" />
       <property name="response-processor" value="response-processor-custom" />
       <property name="channel-manager" value="custom-channel-manager" />
    </request-listener>
</server>


Initially, with one active client connection:
tcp        0      0 my-ip:19806        client-ip:35987      ESTABLISHED

After executing the `telnet` command from the server, a second connection is successfully established alongside the first one:
tcp        0      0 my-ip:19806        client-ip:35987      ESTABLISHED
tcp        0      0 my-ip:19806        my-ip:43698          ESTABLISHED

(Note: If this were running on jPOS Version 1, any subsequent telnet attempt when maxSessions=1 would immediately be rejected with a Connection refused error at the socket level).

<log realm="my-iso-server.server.session/client-ip:35987" at="2026-10-14T16:24:20.000176596">
  <info>
    SessionEnd[connections=17, permits=1, info=Socket[addr=/client-ip,port=35987,localport=19806]]
  </info>
</log>
<log realm="my-iso-server.server.session" at="2026-10-14T16:24:20.002246237">
  <info>
    SessionStart[connections=17, permits=1, info=Socket[addr=/my-ip,port=43698,localport=19806]]
  </info>
</log>

My questions:

Why does QServer in jPOS 3 still accept and trigger SessionStart for subsequent connections when maxSessions is set to 1 and the previous connection is still active (unlike jPOS 1 which threw Connection refused)?

How can I strictly enforce that only 1 active connection is allowed at a time, and automatically reject or drop any incoming second connection immediately?

Any advice or explanation would be highly appreciated. Thank you!

[alcarraz]

Hi,

(Reposted: my earlier reply was accidentally sent by email, which broke its formatting, so I deleted it.)

From the log format (SessionStart[connections=17, permits=1, info=...]) it looks like you're on jPOS 3.0.0. In that version connections is the cumulative number of accepted connections since startup, not the active count; 3.0.1+ reports active connections instead. That's cosmetic, though: the behavior you describe is present in every 3.x release, including the latest 3.0.2.

Why the second connection is accepted

In jPOS 1/2, ISOServer used a ThreadPool. pool.execute(session) took a slot synchronously in the accept loop, so on the next iteration the loop saw pool.getAvailableCount() <= 0, closed the ServerSocket, and new connections got Connection refused.

jPOS 3 replaced the pool with a thread-per-task executor plus a Semaphore, but the permit is acquired inside the submitted task, not in the accept loop:

channel.accept(serverSocket);
...
executor.submit(() -> {
    try {
        permits.acquireUninterruptibly();   // runs later, on the session thread
        createSession(channel).run();
    } finally {
        permits.release();
    }
});

So with maxSessions=1:

1. Client A connects; its task is submitted and the loop immediately re-checks permits.availablePermits() <= 0. A's session thread usually hasn't acquired the permit yet, so the check passes and the loop goes back to accept() with the socket still listening.
2. Your telnet connects. It's accepted (ESTABLISHED), and its session thread parks on acquireUninterruptibly().
3. When A's session ends, the telnet session gets the permit and starts. That's exactly the SessionEnd ... 35987 followed by SessionStart ... 43698 in your log.

Net effect: with connections arriving one at a time, you get maxSessions active sessions plus one extra connection that is accepted and queued; after that the loop sees zero permits and closes the server socket, so further connects are refused. Under a burst of simultaneous connects, though, several can be accepted before any permit is actually taken.

Enforcing a single connection

The proper fix belongs in ISOServer: acquire the permit in the accept loop before submitting the session, and release it in the task's finally. That restores the jPOS 1/2 behavior of closing the listening socket and refusing further connects. I've opened #794 to track it.

Until then, you can work around it without patching jPOS by adding a connection-listener to your QServer that drops any connection beyond the first:

public class SingleSessionGuard implements ISOServerEventListener {
    private final AtomicInteger open = new AtomicInteger();

    @Override
    public void handleISOServerEvent(EventObject ev) {
        if (ev instanceof ISOServerAcceptEvent ae) {
            if (open.incrementAndGet() > 1) {
                try { ((ISOChannel) ae.getISOChannel()).disconnect(); } catch (IOException ignored) { }
            }
        } else if (ev instanceof ISOServerClientDisconnectEvent) {
            open.decrementAndGet();
        }
    }
}

<connection-listener class="com.example.SingleSessionGuard"/>

With this, the second client sees a TCP connect followed by an immediate close rather than Connection refused. Because the listening socket is still open, the kernel completes the handshake before jPOS gets a say, so closing the accepted connection is the earliest a listener can act.

The counter does run one too high for a while: the dropped channel's task is still parked on the semaphore, so its disconnect event only fires after the first session ends and that task runs (and fails immediately). This is mostly harmless, because during that time the server socket is closed and new connects are refused anyway. The loop reopens the socket only once a permit is free. A legitimate new connection could be wrongly dropped only if it were accepted in the instant between the first session releasing its permit and the parked task grabbing it, which is very unlikely in practice.

[chu-ngoc-hai]

Dear @alcarraz

Thank you so much for the detailed breakdown and explanation!

I implemented the workaround using SingleSessionGuard along with
( connection-listener class="com.example.SingleSessionGuard" )
and it works as expected.

I'll keep an eye on issue #794 and look forward to the fix in a future release. Thanks again for opening the issue and sharing this solution!

Good luck to you!