GATTServerConnection.close() does not invoke GATTServer.onDisconnect

[stc1988]

Build environment: macOS
Moddable SDK version: 8.2.0 + #1625
Target device: Moddable Six

Summary

On ESP32, calling GATTServerConnection.close() terminates the BLE link, but the corresponding GATTServer.onDisconnect callback is not invoked.

Expected Behavior

GATTServer.onDisconnect(connection) should be invoked once whenever an established server connection ends, regardless of who initiated the disconnection:

• the remote peer disconnects;
• the BLE stack reports a link loss;
• the application calls GATTServerConnection.close().

GATTServerConnection.close() requests a BLE disconnection, but the physical link termination is asynchronous. The callback should therefore be delivered when NimBLE reports the disconnect event, not synchronously from close().

This gives applications one consistent place to:

• update connection state;
• release per-connection resources;
• restart advertising;
• begin a BLE role transition after the previous link has ended.

When the application calls:

connection.close();

the ESP32 implementation immediately removes and frees the native connection record:

moddable/modules/io/ble/server/esp32/bleserver.c

Lines 1129 to 1147 in 52fe713

	void xs_gattserverconnection_close(xsMachine *the)
	{
	BLEGATTServerConnection connection = xsmcGetHostDataValidate(xsThis, xs_gattserverconnection_destructor);
	BLEServer server = connection->server;
	ble_gap_terminate(connection->conn_handle, BLE_ERR_REM_USER_CONN_TERM);
	xsmcSetHostData(xsThis, C_NULL);
	if (connection == server->connections)
	server->connections = connection->next;
	else {
	BLEGATTServerConnection walker = server->connections;
	while (walker->next)
	walker = walker->next;
	walker->next = connection->next;
	}
	c_free(connection);
	}

Later, when NimBLE reports the actual disconnect, deliverDisconnect() cannot find the connection and returns without invoking onDisconnect:

moddable/modules/io/ble/server/esp32/bleserver.c

Lines 863 to 871 in 52fe713

	static void deliverDisconnect(void *theIn, void *refcon, uint8_t *message, uint16_t messageLength)
	{
	xsMachine *the = theIn;
	BLEServer server = refcon;
	struct ble_gap_conn_desc *conn = (struct ble_gap_conn_desc *)message;
	BLEGATTServerConnection connection = findConnection(server, conn->conn_handle);
	if (C_NULL == connection)
	return; // ready called close on connection instance

As a result, remotely initiated disconnections invoke onDisconnect, while locally initiated disconnections through connection.close() do not.

Application Impact

An application that waits for onDisconnect before starting its next operation remains blocked after calling connection.close().

For example, an Apple Media Service accessory may:

1. accept a temporary peripheral connection from iOS;
2. pair and record the peer address;
3. call connection.close();
4. wait for onDisconnect;
5. connect back to the same peer as a GATT client.

Step 4 never occurs with the current ESP32 implementation. A timer can work around this behavior, but it does not confirm that the previous BLE link has actually ended.

Proposed SDK Behavior

xs_gattserverconnection_close() should request termination without removing the connection record:

1. Mark the connection as closing.
2. Call ble_gap_terminate().
3. Keep the connection in server->connections.
4. When NimBLE reports the disconnect, invoke GATTServer.onDisconnect(connection).
5. Invalidate the JavaScript host data and free the native record after the callback.

The closing flag should make repeated calls to close() harmless while termination is pending.

Example structure:

struct BLEGATTServerConnectionRecord {
    struct BLEGATTServerConnectionRecord *next;
    struct BLEServerRecord *server;
    xsSlot *obj;
    uint16_t conn_handle;
    uint16_t maximumWrite;
    uint8_t closing;
};

Example close behavior:

void xs_gattserverconnection_close(xsMachine *the)
{
    BLEGATTServerConnection connection =
        xsmcGetHostDataValidate(xsThis, xs_gattserverconnection_destructor);

    if (connection->closing)
        return;

    connection->closing = 1;
    ble_gap_terminate(
        connection->conn_handle,
        BLE_ERR_REM_USER_CONN_TERM
    );
}

The existing deliverDisconnect() path can then remain responsible for callback delivery, list removal, host-data invalidation, and freeing the connection.

I’m using this approach and it seems to work well, but I’m not very familiar with the native implementation side, so I’m not confident whether this is the right approach.

Other information

appleMediaService.zip

This is the AMS application that reproduces the issue. It’s possible that my implementation is incorrect, but there are two other issues besides the one discussed here:

• The device cannot be discovered from the iOS Bluetooth settings screen, so I connect to it using an app such as nRF Connect.
• After pairing with the BLE server, onSecure is not triggered, so I added an encrypted Battery Service to force encryption.

[phoddie]

Thank you for the detailed report. My takeaway is that everything is working as intended, so there is no bug. I understand that you want to know when a connection's termination is complete. That's reasonable. Then the question becomes how to achieve that.

The GATTServer is an ECMA-419 API. Consequently, any changes must conform to its design rules. Of note here, the Base Class Pattern defines that the close() method may not invoke any callbacks after being called.

An alternate approach would be to add a disconnect() method to GATTServerConnection. It would look about like your xs_gattserverconnection_close(). We'd also want to update the implementation of close() so that it conforms to the requirement that "It is not an error to call the close method more than once."

After pairing with the BLE server, onSecure is not triggered, so I added an encrypted Battery Service to force encryption.

BLE has two different ways of triggering the security negotiation. It can happen immediately when the connection is established or it can be deferred until an encrypted property is accessed. The GATTServer supports both models using the immediate property in its constructor options object.

[stc1988]

Thank you for confirming.

An alternate approach would be to add a disconnect() method to GATTServerConnection. It would look about like your xs_gattserverconnection_close(). We'd also want to update the implementation of close() so that it conforms to the requirement that "It is not an error to call the close method more than once."

That certainly seems like the straightforward approach. It would be great if we could update the API documentation to make the distinction between close and disconnect clearer.

It can happen immediately when the connection is established or it can be deferred until an encrypted property is accessed. The GATTServer supports both models using the immediate property in its constructor options object.

I’m using the immediate property, but it looks like onSecured is not being invoked.

this.#server = new GATTServer({
	security: {
		bond: true,
		ioCapabilities: "none",
		immediate: true,
	},

[phoddie]

It would be great if we could update the API documentation to make the distinction between close and disconnect clearer.

There is no documentation about this to make "clearer" since this is a discussion of a future API.

I’m using the immediate property, but it looks like onSecured is not being invoked.

I'm confident that the security negotiation is being triggered on connection when immediate is set. You can see that here. Perhaps macOS requires a different incapabilities? Anyway. If there is more to discuss about that, please open a separate issue.