session: attach! returns SurrealSession wrapper

Author: danvinci

src/session.jl

@@ -32,27 +32,30 @@ end
 # --- v3+ Sessions (attach/detach) ---
 
 """
-    attach!(client)
+    attach!(client) -> SurrealSession
 
-Create a new ephemeral session on the server (SurrealDB v3+).
+Create a new ephemeral session on the server (SurrealDB v3+) and return a
+[`SurrealSession`](@ref) wrapper. The session is independent: its own
+namespace, database, auth, and variables. Close with [`close!`](@ref).
 
-Returns a `UUID` session identifier. The session is independent — it has its
-own namespace, database, auth, and variables. Use [`detach!`](@ref) to clean up.
+Matches the wrapped-session API used by surrealdb-go (`db.Attach`),
+surrealdb-py (`AsyncSurrealSession` / `BlockingSurrealSession`), and
+surrealdb-js (`newSession`).
 
 WebSocket-only (not supported on HTTP connections).
 """
-function attach!(client::SurrealClient{<:RemoteWSConnection})
+function attach!(client::SurrealClient{C}) where {C<:RemoteWSConnection}
     sid = UUIDs.uuid4()
     _rpc_call(client, "attach", Any[]; session=sid)
-    return sid
+    return SurrealSession{C}(client, sid)
 end
 
 """
     detach!(client, session_id::UUID)
 
-Destroy a server-side session (SurrealDB v3+).
-
-After detaching, the session cannot be used for further operations.
+Destroy a server-side session by raw UUID (SurrealDB v3+). Prefer
+[`close!`](@ref) on a [`SurrealSession`](@ref); use this when you only have
+a bare UUID (e.g. from [`sessions`](@ref) listing).
 """
 function detach!(client::SurrealClient{<:RemoteWSConnection}, session_id)
     _rpc_call(client, "detach", Any[]; session=session_id)
@@ -102,6 +105,19 @@ mutable struct SurrealSession{C<:AbstractConnection}
     session_id::UUID
 end
 
+Base.show(io::IO, s::SurrealSession) = print(io, "SurrealSession(", s.session_id, ")")
+
+"""
+    close!(session::SurrealSession)
+
+Destroy the server-side session. After closing, the session must not be used.
+Wraps [`detach!`](@ref).
+"""
+function close!(session::SurrealSession{<:RemoteWSConnection})
+    detach!(session.client, session.session_id)
+    return nothing
+end
+
 """
     begin!(session::SurrealSession)
 

test/test_session.jl

@@ -77,17 +77,17 @@ end
 
 # --- v3+ Sessions (attach/detach) ---
 
-@testset "attach!/detach!/sessions roundtrip (v3+)" begin
+@testset "attach!/close!/sessions roundtrip (v3+)" begin
     # v2 doesn't implement the attach RPC; gate via version probe.
     ver = try; string(SurrealDB.version(client)); catch; ""; end
     if occursin(r"surrealdb-2\.", ver)
-        @info "Skipping attach!/detach! — v2 server doesn't support v3 sessions"
+        @info "Skipping attach!/close! — v2 server doesn't support v3 sessions"
     else
-        sid = SurrealDB.attach!(client)
-        @test sid isa UUIDs.UUID
-        @test sid in SurrealDB.sessions(client)
-        SurrealDB.detach!(client, sid)
-        @test !(sid in SurrealDB.sessions(client))
+        sess = SurrealDB.attach!(client)
+        @test sess isa SurrealDB.SurrealSession
+        @test sess.session_id in SurrealDB.sessions(client)
+        SurrealDB.close!(sess)
+        @test !(sess.session_id in SurrealDB.sessions(client))
     end
 end