Phoenix500526 opened a new pull request, #12237:
URL: https://github.com/apache/arrow-rs/pull/12237

   # Which issue does this PR close?
   
   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](https://github.com/apache/arrow-flight-sql-postgresql/issues/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](https://github.com/apache/arrow/pull/34817) introduced the 
standard session-management messages, including `CloseSession`.
   
   As reported in 
[#6516](https://github.com/apache/arrow-rs/issues/6516#issuecomment-2562108443),
 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.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to