cosocket integration for legacy client libraries

I have a wrapper module which integrates the OpenLDAP client library, libldap, with Nginx/OpenResty using the internal C APIs. It works, but this is quite fragile as ABI compatibility isn't maintained between release versions of NGINX.

libldap has no capability to ingest or excrete data via buffers, but it will initialise a handle around a file descriptor. We currently create the socket using ngx.socket.tcp connect it using sock:connect, and then pass it off to a C function which extracts the file descriptor and wraps it in a libldap connection.

There's unlikely to be any appetite on the NGINX side for stabilising the ABI or creating public APIs, I'm wondering if there's any appetite on the OpenResty side for extending the existing set of Lua functions to allow these kinds of integrations?

The initial set of additional functions could be:

socket:readable() - Returns immediately if data is ready to read, or yields, and resumes when data is ready, behaves similarly to receive()
socket:writable() - Returns immediately if the socket is writable, or yields, and resumes when data can be written.
socket:descriptor() or socket:fd() - Returns the underlying file descriptor.

It may also be useful to specify an onclose() callback to execute if the socket is garbage collected, but this can be worked around to some degree by destroying and reinitialising library handles on every request.

To be clear, I'm not expecting a maintainer of the OpenResty project to write this code. I'm happy to raise a PR. I just wanted to have a discussion first to see if this is something that'd even be entertained.

There are likely good design reasons behind the very compact socket API OpenResty exposes today. Exposing the file descriptor likely breaks some existing assumptions. It might be better to add an accessor function to a C API to prevent misuse, it'd still provide the stability we're looking for.

readable() and writable() seem less contentious and have general utility beyond non-Lua or 3rd party modules, as they'd allow more advanced scheduling and flows. With timeout 0, readable and writable would both be low cost using recv(..., MSG_PEEK | MSG_DONTWAIT) and send(fd, 0, NULL, MSG_DONTWAIT) to test readability and writability respectively.

Start with the existing ngx.socket.tcp and sock:connect entry points and review how the current Lua socket API handles readiness, file descriptors, and cleanup. Compare the proposed readable(), writable(), descriptor()/fd(), and onclose() behaviors with the libldap integration needs and ABI concerns. Done requires an agreed API design and maintainer acceptance; no specific file or test is named.