From 6a53da6ddea3bf1cfb835ac22e33a85416051429 Mon Sep 17 00:00:00 2001 From: Matt Dale <9760375+matthewdale@users.noreply.github.com> Date: Tue, 7 May 2024 17:35:15 -0700 Subject: [PATCH] GODRIVER-3180 Document clearly that x/ package APIs are not stable. (#1631) --- x/README.md | 11 +++++--- x/bsonx/bsoncore/doc.go | 23 +++++++++------- x/mongo/driver/DESIGN.md | 27 ------------------- x/mongo/driver/auth/creds/doc.go | 14 ++++++++++ x/mongo/driver/auth/doc.go | 21 +++++---------- x/mongo/driver/connstring/connstring.go | 7 +++++ x/mongo/driver/dns/dns.go | 7 +++++ x/mongo/driver/driver.go | 7 +++++ x/mongo/driver/drivertest/doc.go | 14 ++++++++++ x/mongo/driver/integration/doc.go | 14 ++++++++++ .../mongocrypt/mongocrypt_not_enabled.go | 7 +++++ x/mongo/driver/mongocrypt/options/doc.go | 14 ++++++++++ x/mongo/driver/ocsp/ocsp.go | 7 +++++ x/mongo/driver/operation/doc.go | 14 ++++++++++ x/mongo/driver/session/doc.go | 14 ++++++++++ x/mongo/driver/topology/topology.go | 17 +++++++++--- x/mongo/driver/wiremessage/wiremessage.go | 7 +++++ 17 files changed, 166 insertions(+), 59 deletions(-) delete mode 100644 x/mongo/driver/DESIGN.md create mode 100644 x/mongo/driver/auth/creds/doc.go create mode 100644 x/mongo/driver/drivertest/doc.go create mode 100644 x/mongo/driver/integration/doc.go create mode 100644 x/mongo/driver/mongocrypt/options/doc.go create mode 100644 x/mongo/driver/operation/doc.go create mode 100644 x/mongo/driver/session/doc.go diff --git a/x/README.md b/x/README.md index 6d8800a014..e55329b1a5 100644 --- a/x/README.md +++ b/x/README.md @@ -1,6 +1,9 @@ -# MongoDB Go Driver Unstable Libraries +# MongoDB Go Driver Experimental Packages -This directory contains unstable MongoDB Go driver libraries and packages. The APIs of these -packages are not stable and there is no backward compatibility guarantee. +**WARNING: THESE PACKAGES ARE EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED +WITHOUT NOTICE.** -**THESE PACKAGES ARE EXPERIMENTAL AND SUBJECT TO CHANGE.** +This directory contains packages intended only for internal use. They are made +available to facilitate use cases that require access to internal MongoDB driver +functionality and state. The APIs of these packages are not stable and there is +no backward compatibility guarantee. Use with extreme caution! diff --git a/x/bsonx/bsoncore/doc.go b/x/bsonx/bsoncore/doc.go index 6837b53fc5..f68e1da1a0 100644 --- a/x/bsonx/bsoncore/doc.go +++ b/x/bsonx/bsoncore/doc.go @@ -4,10 +4,18 @@ // 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 -// Package bsoncore contains functions that can be used to encode and decode BSON -// elements and values to or from a slice of bytes. These functions are aimed at -// allowing low level manipulation of BSON and can be used to build a higher -// level BSON library. +// Package bsoncore is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! +// +// Package bsoncore contains functions that can be used to encode and decode +// BSON elements and values to or from a slice of bytes. These functions are +// aimed at allowing low level manipulation of BSON and can be used to build a +// higher level BSON library. // // The Read* functions within this package return the values of the element and // a boolean indicating if the values are valid. A boolean was used instead of @@ -15,15 +23,12 @@ // enough bytes. This library attempts to do no validation, it will only return // false if there are not enough bytes for an item to be read. For example, the // ReadDocument function checks the length, if that length is larger than the -// number of bytes available, it will return false, if there are enough bytes, it -// will return those bytes and true. It is the consumers responsibility to +// number of bytes available, it will return false, if there are enough bytes, +// it will return those bytes and true. It is the consumers responsibility to // validate those bytes. // // The Append* functions within this package will append the type value to the // given dst slice. If the slice has enough capacity, it will not grow the // slice. The Append*Element functions within this package operate in the same // way, but additionally append the BSON type and the key before the value. -// -// Warning: Package bsoncore is unstable and there is no backward compatibility -// guarantee. It is experimental and subject to change. package bsoncore diff --git a/x/mongo/driver/DESIGN.md b/x/mongo/driver/DESIGN.md deleted file mode 100644 index 3c3e6c56cd..0000000000 --- a/x/mongo/driver/DESIGN.md +++ /dev/null @@ -1,27 +0,0 @@ -# Driver Library Design - -This document outlines the design for this package. - -## Deployment, Server, and Connection - -Acquiring a `Connection` from a `Server` selected from a `Deployment` enables sending and receiving -wire messages. A `Deployment` represents an set of MongoDB servers and a `Server` represents a -member of that set. These three types form the operation execution stack. - -### Compression - -Compression is handled by Connection type while uncompression is handled automatically by the -Operation type. This is done because the compressor to use for compressing a wire message is -chosen by the connection during handshake, while uncompression can be performed without this -information. This does make the design of compression non-symmetric, but it makes the design simpler -to implement and more consistent. - -## Operation - -The `Operation` type handles executing a series of commands using a `Deployment`. For most uses -`Operation` will only execute a single command, but the main use case for a series of commands is -batch split write commands, such as insert. The type itself is heavily documented, so reading the -code and comments together should provide an understanding of how the type works. - -This type is not meant to be used directly by callers. Instead a wrapping type should be defined -using the IDL. diff --git a/x/mongo/driver/auth/creds/doc.go b/x/mongo/driver/auth/creds/doc.go new file mode 100644 index 0000000000..99c4c3470f --- /dev/null +++ b/x/mongo/driver/auth/creds/doc.go @@ -0,0 +1,14 @@ +// Copyright (C) MongoDB, Inc. 2024-present. +// +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// 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 + +// Package creds is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! +package creds diff --git a/x/mongo/driver/auth/doc.go b/x/mongo/driver/auth/doc.go index 9db65cf193..5f9f1f5743 100644 --- a/x/mongo/driver/auth/doc.go +++ b/x/mongo/driver/auth/doc.go @@ -4,20 +4,11 @@ // 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 -// Package auth is not for public use. +// Package auth is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. // -// The API for packages in the 'private' directory have no stability -// guarantee. -// -// The packages within the 'private' directory would normally be put into an -// 'internal' directory to prohibit their use outside the 'mongo' directory. -// However, some MongoDB tools require very low-level access to the building -// blocks of a driver, so we have placed them under 'private' to allow these -// packages to be imported by projects that need them. -// -// These package APIs may be modified in backwards-incompatible ways at any -// time. -// -// You are strongly discouraged from directly using any packages -// under 'private'. +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! package auth diff --git a/x/mongo/driver/connstring/connstring.go b/x/mongo/driver/connstring/connstring.go index 52068b8ea8..686458e292 100644 --- a/x/mongo/driver/connstring/connstring.go +++ b/x/mongo/driver/connstring/connstring.go @@ -4,6 +4,13 @@ // 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 +// Package connstring is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! package connstring // import "go.mongodb.org/mongo-driver/x/mongo/driver/connstring" import ( diff --git a/x/mongo/driver/dns/dns.go b/x/mongo/driver/dns/dns.go index 6573a4c1ad..9334d493ed 100644 --- a/x/mongo/driver/dns/dns.go +++ b/x/mongo/driver/dns/dns.go @@ -4,6 +4,13 @@ // 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 +// Package dns is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! package dns import ( diff --git a/x/mongo/driver/driver.go b/x/mongo/driver/driver.go index 5fd3ddcb42..900729bf87 100644 --- a/x/mongo/driver/driver.go +++ b/x/mongo/driver/driver.go @@ -4,6 +4,13 @@ // 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 +// Package driver is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! package driver // import "go.mongodb.org/mongo-driver/x/mongo/driver" import ( diff --git a/x/mongo/driver/drivertest/doc.go b/x/mongo/driver/drivertest/doc.go new file mode 100644 index 0000000000..dea15f41e4 --- /dev/null +++ b/x/mongo/driver/drivertest/doc.go @@ -0,0 +1,14 @@ +// Copyright (C) MongoDB, Inc. 2024-present. +// +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// 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 + +// Package drivertest is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! +package drivertest diff --git a/x/mongo/driver/integration/doc.go b/x/mongo/driver/integration/doc.go new file mode 100644 index 0000000000..3e3b3cec7b --- /dev/null +++ b/x/mongo/driver/integration/doc.go @@ -0,0 +1,14 @@ +// Copyright (C) MongoDB, Inc. 2024-present. +// +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// 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 + +// Package integration is intended for internal use only. It is made available +// to facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! +package integration diff --git a/x/mongo/driver/mongocrypt/mongocrypt_not_enabled.go b/x/mongo/driver/mongocrypt/mongocrypt_not_enabled.go index 24f9f9b0ec..80f500085c 100644 --- a/x/mongo/driver/mongocrypt/mongocrypt_not_enabled.go +++ b/x/mongo/driver/mongocrypt/mongocrypt_not_enabled.go @@ -7,6 +7,13 @@ //go:build !cse // +build !cse +// Package mongocrypt is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! package mongocrypt import ( diff --git a/x/mongo/driver/mongocrypt/options/doc.go b/x/mongo/driver/mongocrypt/options/doc.go new file mode 100644 index 0000000000..e0cc77052a --- /dev/null +++ b/x/mongo/driver/mongocrypt/options/doc.go @@ -0,0 +1,14 @@ +// Copyright (C) MongoDB, Inc. 2024-present. +// +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// 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 + +// Package options is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! +package options diff --git a/x/mongo/driver/ocsp/ocsp.go b/x/mongo/driver/ocsp/ocsp.go index 8700728729..2bff94a659 100644 --- a/x/mongo/driver/ocsp/ocsp.go +++ b/x/mongo/driver/ocsp/ocsp.go @@ -4,6 +4,13 @@ // 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 +// Package ocsp is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! package ocsp import ( diff --git a/x/mongo/driver/operation/doc.go b/x/mongo/driver/operation/doc.go new file mode 100644 index 0000000000..e55b12a748 --- /dev/null +++ b/x/mongo/driver/operation/doc.go @@ -0,0 +1,14 @@ +// Copyright (C) MongoDB, Inc. 2024-present. +// +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// 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 + +// Package operation is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! +package operation diff --git a/x/mongo/driver/session/doc.go b/x/mongo/driver/session/doc.go new file mode 100644 index 0000000000..80b2ac2dd5 --- /dev/null +++ b/x/mongo/driver/session/doc.go @@ -0,0 +1,14 @@ +// Copyright (C) MongoDB, Inc. 2024-present. +// +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// 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 + +// Package session is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! +package session diff --git a/x/mongo/driver/topology/topology.go b/x/mongo/driver/topology/topology.go index 3dbbcfb860..0fb913d21b 100644 --- a/x/mongo/driver/topology/topology.go +++ b/x/mongo/driver/topology/topology.go @@ -4,10 +4,19 @@ // 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 -// Package topology contains types that handles the discovery, monitoring, and selection -// of servers. This package is designed to expose enough inner workings of service discovery -// and monitoring to allow low level applications to have fine grained control, while hiding -// most of the detailed implementation of the algorithms. +// Package topology is intended for internal use only. It is made available to +// facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! +// +// Package topology contains types that handles the discovery, monitoring, and +// selection of servers. This package is designed to expose enough inner +// workings of service discovery and monitoring to allow low level applications +// to have fine grained control, while hiding most of the detailed +// implementation of the algorithms. package topology // import "go.mongodb.org/mongo-driver/x/mongo/driver/topology" import ( diff --git a/x/mongo/driver/wiremessage/wiremessage.go b/x/mongo/driver/wiremessage/wiremessage.go index a13dda4e89..fbdd21753f 100644 --- a/x/mongo/driver/wiremessage/wiremessage.go +++ b/x/mongo/driver/wiremessage/wiremessage.go @@ -4,6 +4,13 @@ // 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 +// Package wiremessage is intended for internal use only. It is made available +// to facilitate use cases that require access to internal MongoDB driver +// functionality and state. The API of this package is not stable and there is +// no backward compatibility guarantee. +// +// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT +// NOTICE! USE WITH EXTREME CAUTION! package wiremessage import (