Support UNIX domain sockets for testing APIs

[tristan957]

I have been working on revamping the REST support in our storage engine and have worked on drafting an OpenAPI document during the process. On initialization of our storage engine, we create a UNIX domain socket and spwan a REST server so that users can query information and make requests to the storage engine at runtime outside the normal operation of the main application (MongoDB, for instance).

An example request:

curl -i -X GET --unix-socket /tmp/hse.sock http://localhost/perfc?pretty=true

One of the best features of OpenAPI is that applications that render a document can often allow you to test an API given the servers value. Unfortunately, without a way to specify a UNIX domain socket, the testing portion of the rendered document doesn't work. Even more unfortunately, there is no standard URL scheme for denoting a UNIX domain socket. Discussion has previously taken place here.

Though I have no expectations that this issue will go anywhere, I wanted to bring it up.

[handrews]

The @OAI/tsc has repeatedly defined the scope of the OpenAPI Specification as HTTP APIs, so I'm going to close this as out-of-scope. It might be useful, but it would raise complex questions about what other non-HTTP addressing would need to be supported. Also, there's nothing preventing a tool from defining its own way to talk to a socket in place of HTTP URIs (if I understand what's going on here correctly).

[tristan957]

I'm not sure that I'm following your comment. The use case is an HTTP REST server that communicates with clients over a Unix socket. Instead of defining a REST server like http://localhost:8080, I want to set http+unix://%2Ftmp%2Fprofilesvc.sock/path/to/page. Is that more clear?

[tristan957]

Document in question: https://github.com/hse-project/hse/blob/master/docs/openapi.json

[handrews]

It's not clear to me why that ought to fit here, but it is clear to me that I did not understand your proposal well enough to close it 😅

I'll re-open this and we'll revisit it as we go through the OAI-scope labeled issues.

[tristan957]

I'm on mobile at the moment, but I'll try to be a little more specific next week.

[LasneF]

to me looks corner case topic,
as i cannot found an RFC defining unix socket or any official document about it ,
it s an implementation (details) for setting an IPC communication
as soon as there is no URI model defined for it , i do not beleive it s up to OAS to specify how a communication has to be established and stay in main stream approach

to me should go to private extension