GODRIVER-3612 Add an internal-only NewSessionWithLSID API (v2) #2177

matthewdale · 2025-08-22T18:33:18Z

Summary

Add an internal-only API mongo.NewSessionWithLSID that returns a *Session for the specified Client and session ID document.

Background & Motivation

mongodb-drivers-pr-bot · 2025-08-22T18:38:07Z

API Change Report

No changes found!

mongodb-drivers-pr-bot · 2025-08-22T18:39:01Z

🧪 Performance Results

Commit SHA: 03adad0

The following benchmark tests for version 68b22835a327320007f01f24 had statistically significant changes (i.e., |z-score| > 1.96):

Benchmark	Measurement	% Change	Patch Value	Stable Region	H-Score	Z-Score
BenchmarkBSONFlatDocumentEncoding	ns_per_op	4.9834	16422.0000	Avg: 15642.4688 Med: 15600.5000 Stdev: 383.4528	0.7308	2.0329
BenchmarkBSONDeepDocumentDecoding	total_bytes_allocated	-2.5139	245528776.0000	Avg: 251860213.4194 Med: 252330328.0000 Stdev: 3023314.2474	0.7329	-2.0942
BenchmarkBSONDeepDocumentDecoding	total_mem_allocs	-2.4551	11305294.0000	Avg: 11589832.4194 Med: 11611115.0000 Stdev: 138499.4358	0.7275	-2.0544
BenchmarkLargeDocInsertOne	allocated_bytes_per_op	-0.2863	5643.0000	Avg: 5659.2000 Med: 5660.0000 Stdev: 6.1085	0.8134	-2.6520
BenchmarkBSONDeepDocumentDecoding	allocated_bytes_per_op	-0.0609	15094.0000	Avg: 15103.1935 Med: 15104.0000 Stdev: 2.3723	0.9183	-3.8753

For a comprehensive view of all microbenchmark results for this PR's commit, please check out the Evergreen perf task for this patch.

Copilot

Pull Request Overview

This PR adds an internal-only API mongo.NewSessionWithID that creates a *Session for a specified Client and session ID document. This API is intended for internal use cases where specific session IDs need to be used rather than letting the driver generate them automatically.

Introduces NewSessionWithID function that constructs sessions with custom session ID documents
Implements build tag protection (//go:build mongointernal) to restrict usage to internal builds only
Updates CI configuration to enable the mongointernal build tag in tests

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
mongo/mongointernal.go	Implements the new `NewSessionWithID` API with proper documentation and build tag restrictions
internal/integration/mongointernal_test.go	Adds comprehensive tests covering both successful usage and expected panic behavior
.evergreen/config.yml	Updates CI build tags to include `mongointernal` for proper test execution

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

prestonvasquez

I'm concerned about users using session.Client methods that involve a pool. Or worse, maintainers adding a new method to session.Client that requires accessing the pool and forgetting to document that behavior for NewSessionWithID.

I've created GODRIVER-3649 to follow up on this in 3.0.

prestonvasquez · 2025-08-28T22:41:25Z

mongo/mongointernal.go

+//
+// NewSessionWithID is intended only for internal use and may be changed or
+// removed at any time.
+func NewSessionWithID(client *Client, sessionID bson.Raw) *Session {


[nit] Suggest renaming this function to NewSessionWithLSID

prestonvasquez · 2025-08-28T22:49:07Z

mongo/mongointernal.go

+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+//go:build mongointernal


[non-blocking] Should we name this mongointernal_lsid to keep it separate from any future code we may want to gate behind a mongointernal build tag?

I'm concerned too many build tags will become a maintenance headache, both for us and for the internal teams who use the Go Driver. I'm assuming that an app that uses one internal-only API may need to use many internal-only APIs, and keeping track of a list of build tags may become onerous.

Is there a scenario you're thinking of where it's better to have more granular build tags?

Is there a scenario you're thinking of where it's better to have more granular build tags?

No, and the more I think about it it seems unlikely that we will need to use mongointernal often.

prestonvasquez · 2025-08-28T22:55:37Z

internal/integration/mongointernal_test.go

+		mt.Parallel()
+
+		sessionID := bson.Raw(bsoncore.NewDocumentBuilder().
+			AppendBinary("id", 4, []byte{}).


[nit] Suggest using a valid 16-byte UUID to ensure the panic is due to the session being unpooled and not an invalid LSID.

prestonvasquez · 2025-08-28T23:21:15Z

mongo/mongointernal.go

+// subtype 4).
+//
+// Sessions returned by NewSessionWithID are never added to the driver's session
+// pool. Calling EndSession on a Session returned by NewSessionWithID will


[non-blocking] We should include SetServer as API that will panic. I'm not sure why anyone would use it and AFAIK it's only use case happens for implicit sessions, but it's still possible:

sess.Client().SetSrerver() // will panic

Added note that ClientSession().SetServer() will panic and a test to confirm it does.

The base branch was changed.

matthewdale · 2025-09-02T17:14:33Z

I just realized this needs to target release/1.17. I've created #2183 for that.

GODRIVER-3612 Add an internal-only NewSessionWithID API.

9eb374b

matthewdale force-pushed the godriver3612-session-with-id branch from bc7a505 to 9eb374b Compare August 22, 2025 18:47

matthewdale added review-priority-normal Medium Priority PR for Review: within 1 business day feature ignore-for-release labels Aug 27, 2025

matthewdale marked this pull request as ready for review August 27, 2025 01:47

Copilot AI review requested due to automatic review settings August 27, 2025 01:47

matthewdale requested a review from a team as a code owner August 27, 2025 01:47

matthewdale requested a review from qingyang-hu August 27, 2025 01:47

Copilot AI reviewed Aug 27, 2025

View reviewed changes

matthewdale requested review from prestonvasquez and removed request for qingyang-hu August 27, 2025 01:48

prestonvasquez requested changes Aug 28, 2025

View reviewed changes

Rename NewSessionWithID to NewSessionWithLSID and update docs and tests.

03adad0

matthewdale requested a review from prestonvasquez August 29, 2025 22:24

matthewdale changed the title ~~GODRIVER-3612 Add an internal-only NewSessionWithID API.~~ GODRIVER-3612 Add an internal-only NewSessionWithLSID API. Aug 29, 2025

prestonvasquez previously approved these changes Aug 30, 2025

View reviewed changes

matthewdale enabled auto-merge (squash) September 2, 2025 16:53

matthewdale changed the base branch from master to release/1.17 September 2, 2025 16:55

matthewdale changed the base branch from release/1.17 to master September 2, 2025 17:08

matthewdale changed the title ~~GODRIVER-3612 Add an internal-only NewSessionWithLSID API.~~ GODRIVER-3612 Add an internal-only NewSessionWithLSID API (v2) Sep 3, 2025

matthewdale requested a review from prestonvasquez September 3, 2025 02:14

prestonvasquez approved these changes Sep 4, 2025

View reviewed changes

matthewdale merged commit b79c3f6 into mongodb:master Sep 4, 2025
36 of 37 checks passed

GODRIVER-3612 Add an internal-only NewSessionWithLSID API (v2) #2177

GODRIVER-3612 Add an internal-only NewSessionWithLSID API (v2) #2177

Uh oh!

Conversation

matthewdale commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Background & Motivation

Uh oh!

mongodb-drivers-pr-bot bot commented Aug 22, 2025

API Change Report

Uh oh!

mongodb-drivers-pr-bot bot commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 Performance Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

prestonvasquez left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewdale Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewdale Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Aug 30, 2025

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewdale Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewdale Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

matthewdale commented Sep 2, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

matthewdale commented Aug 22, 2025 •

edited

Loading

mongodb-drivers-pr-bot bot commented Aug 22, 2025 •

edited

Loading

prestonvasquez left a comment •

edited

Loading

prestonvasquez Aug 28, 2025 •

edited

Loading

prestonvasquez Aug 28, 2025 •

edited

Loading

prestonvasquez Aug 28, 2025 •

edited

Loading

prestonvasquez Aug 28, 2025 •

edited

Loading