Skip to content

Add SSLSocket server handshake aliases - #1094

Draft
samuel-williams-shopify wants to merge 1 commit into
ruby:masterfrom
samuel-williams-shopify:add-ssl-socket-start
Draft

Add SSLSocket server handshake aliases#1094
samuel-williams-shopify wants to merge 1 commit into
ruby:masterfrom
samuel-williams-shopify:add-ssl-socket-start

Conversation

@samuel-williams-shopify

Copy link
Copy Markdown
Contributor

TL;DR

Add OpenSSL::SSL::SSLSocket#start and #start_nonblock as aliases for #accept and #accept_nonblock.

Context

When OpenSSL::SSL::SSLServer#start_immediately is disabled, SSLServer#accept returns the accepted transport before performing the TLS handshake. The caller then invokes SSLSocket#accept on that already-accepted socket to perform the server-side handshake.

io-endpoint currently defines these aliases itself so accepted connections can be dispatched to a fiber or thread and the TLS handshake can be initiated with #start, without treating handshake initiation as another connection acceptance operation in generic server code.

Related to #760.

Changes

  • Alias SSLSocket#start to SSLSocket#accept.
  • Alias SSLSocket#start_nonblock to SSLSocket#accept_nonblock.
  • Test that both aliases resolve to the existing methods.

The existing methods and behavior are unchanged.

Tophatting

  • bundle exec rake compile
  • bundle exec ruby -Itest -Ilib test/openssl/test_ssl.rb --name=test_server_handshake_aliases
  • bundle exec rake test (628 tests, 4,606 assertions, 0 failures, 0 errors, 2 expected FIPS omissions)

Add SSLSocket#start and #start_nonblock as aliases for #accept and #accept_nonblock. This gives server code a handshake-oriented name when SSLServer#start_immediately is disabled, while preserving the existing interface and behavior.\n\nRelated to ruby#760.

Assisted-By: devx/3ed43c18-3c9a-4ad9-a6f5-6668caa29658
@rhenium

rhenium commented Aug 19, 2026

Copy link
Copy Markdown
Member

TLS is a client-initiated protocol, so if we had SSLSocket#start I'd expect it to mean #connect rather than #accept.

As I've written in #760, I don't really see problems with the current names #accept and #connect. What problem does adding aliases solve?

SSLSocket#{accept,connect} were taken from the corresponding OpenSSL C API SSL_accept() and SSL_connect(), so they are consistent in this regard at least.

@samuel-williams-shopify

Copy link
Copy Markdown
Contributor Author

Thanks. The concrete problem is that accept cannot represent a post-accept negotiation capability in generic socket-handling code: every socket responds to accept, including sockets representing connections that have already been accepted.

io-endpoint accepts a connection, dispatches it to a fiber or thread, and then performs any required application-level negotiation:

if socket.respond_to?(:start)
  socket.start
end

The actual implementation is here: https://github.com/socketry/io-endpoint/blob/5e7c6aff6ba7b52c1a30f6d3a6e5a5aa86b41bf0/lib/io/endpoint/wrapper.rb#L217-L226

For an SSLSocket returned with SSLServer#start_immediately = false, that operation is the server-side TLS handshake. A plain socket requires no such step.

Therefore, io-endpoint currently adds SSLSocket#start itself as an alias for accept. The distinct name allows generic code to discover and invoke post-accept negotiation without checking for SSLSocket specifically or accidentally calling accept on an ordinary connected socket.

This PR does not replace or change accept and connect; it standardizes that distinct capability name for the server-side handshake.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants