Skip to content

feat(flight)!: support CloseSession - #12237

Open
Phoenix500526 wants to merge 1 commit into
apache:mainfrom
Phoenix500526:issue/6516
Open

Phoenix500526 wants to merge 1 commit into
apache:mainfrom
Phoenix500526:issue/6516

Conversation

@Phoenix500526

@Phoenix500526 Phoenix500526 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Which issue does this PR close?

Part of #11383
Closes #6516.

Rationale for this change

Flight SQL clients need a standard way to notify a server that a session can be released. The discussion started in arrow-flight-sql-postgresql#13: waiting for session timeout retains server resources after the client has finished, while server-specific close actions prevent generic clients from handling this consistently. apache/arrow#34817 introduced the standard session-management messages, including CloseSession.

As reported in #6516, clients such as adbc_driver_flightsql already send this action, but the Rust Flight SQL server does not recognize it. Implementors currently need a do_action_fallback workaround. The Rust SQL client's close() is also a no-op, so calling it does not release a server session.

This PR implements the Rust client and server support. The PostgreSQL adapter still needs its own server implementation; this does not resolve that separate issue.

What changes are included in this PR?

  • Add only CloseSessionRequest and CloseSessionResult to Flight.proto, regenerate the Rust bindings, and export both messages and close_session_result::Status.
  • Implement FlightSqlServiceClient::close() using the configured headers, returning the server's result and draining the response stream so trailing RPC errors are propagated.
  • Advertise and dispatch CloseSession through a new FlightSqlService::do_action_close_session hook. Session identification and resource cleanup remain the service implementor's responsibility; the default hook returns Unimplemented.
  • Add a CLI close-session command and session handling to the SQL server example for manual verification. The example prints the token at handshake so the same session can be closed twice using --token.

Set/GetSessionOptions and other session-management messages are outside this PR's scope.

Are these changes tested?

Four new integration tests cover all defined close statuses and preservation of unknown values; missing or malformed responses and trailing RPC errors; server action discovery, malformed requests, header propagation, session removal and repeated closure; and the default unimplemented hook.

The arrow-flight unit, integration and example suites pass with cli,flight-sql,tls-ring (141 tests). Manual verification against the example confirmed that closing the same token twice returns Closed, then NotFound, with corresponding server output. All-features example tests hit an existing conflict between the two TLS providers; the same failure was reproduced with the unchanged example from the base commit.

Are there any significant user-facing changes?

This draft intentionally proposes a breaking API change and requires a major release.

FlightSqlServiceClient::close() changes from Result<()> to Result<CloseSessionResult> and now sends a request instead of doing nothing. A transport, decoding or response-protocol failure remains an Err; a successfully decoded server result is returned as Ok, leaving status handling to the caller.

The return-type change preserves the information needed to decide whether to retry:

  • Closed: the close request is complete.
  • Closing: closure is in progress; the caller may retry.
  • NotCloseable: the caller should not retry.

Keeping Result<()> would either hide these distinctions or map valid server statuses into errors. In particular, treating Closing as a generic protocol error would make it difficult for callers to distinguish a retryable close status from an actual protocol failure without inspecting error text. Returning the protocol result lets callers apply their own retry policy without adding another close method or imposing automatic retries. Existing callers that require a unit result need to adapt, even though the old method was a no-op. Servers without CloseSession support can now cause close() to return an RPC error.

There is also a server migration requirement: CloseSession is dispatched to do_action_close_session rather than do_action_fallback. Existing implementations that handle it in the fallback should move their session cleanup logic into the new hook; otherwise they will receive the default Unimplemented error. The library handles request decoding and response encoding. This migration is documented on the new hook.

AI usage disclosure

Codex assisted with the implementation, tests, code review and this PR description. The changes were reviewed incrementally with the author, and the author manually verified the same-session close flow. Rust protobuf bindings were generated with the repository's generator.

@boring-cyborg boring-cyborg Bot added the arrow-flight Changes to the arrow-flight crate label Nov 13, 2026
@Phoenix500526
Phoenix500526 marked this pull request as ready for review November 13, 2026 15:06
Allow Flight SQL clients to release server sessions and inspect the
reported status. Support manual verification with the example server
and the CLI close-session command.

BREAKING CHANGE: FlightSqlServiceClient::close now returns
Result<CloseSessionResult> instead of Result<()> and sends a server
request instead of succeeding without doing anything. Callers are
responsible for handling the returned close status.
CloseSession actions now dispatch to do_action_close_session instead
of do_action_fallback. Servers that handled CloseSession in the
fallback should move that logic to the new method; its default
implementation returns Unimplemented.

CLOSE apache#6516
@Phoenix500526

Copy link
Copy Markdown
Contributor Author

@kou in case you're interested in this.

@Rich-T-kid Rich-T-kid added api-change Breaking API change, needs to wait for a major version release enhancement New feature/addition next-major-release the PR has API changes and it waiting on the next major version labels Nov 16, 2026

This branch has not been deployed

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

Labels

api-change Breaking API change, needs to wait for a major version release arrow-flight Changes to the arrow-flight crate enhancement New feature/addition next-major-release the PR has API changes and it waiting on the next major version

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Implement CloseSession in arrow-flight

2 participants