Merge pull request #151 from globalsign/feature/docs

Cleanup

.travis.yml

@@ -3,8 +3,8 @@ language: go
 go_import_path: github.com/globalsign/mgo
 
 go:
-    - 1.8.x
     - 1.9.x
+    - 1.10.x
 
 env:
     global:
@@ -29,7 +29,7 @@ install:
     - go get gopkg.in/check.v1
     - go get gopkg.in/yaml.v2
     - go get gopkg.in/tomb.v2
-    - go get github.com/golang/lint/golint
+    - go get github.com/golang/lint
 
 before_script:
     - golint  ./... | grep -v 'ID' | cat

README.md

@@ -3,9 +3,6 @@
 The MongoDB driver for Go
 -------------------------
 
-This is the "official", maintained fork of `mgo` (pronounced as "mango").
-We are grateful for the great work that @niemeyer and the mgo contributors have made over the years.
-
 This fork has had a few improvements by ourselves as well as several PR's merged from the original mgo repo that are currently awaiting review.
 Changes are mostly geared towards performance improvements and bug fixes, though a few new features have been added.
 
@@ -14,7 +11,7 @@ Further PR's (with tests) are welcome, but please maintain backwards compatibili
 Detailed documentation of the API is available at
 [GoDoc](https://godoc.org/github.com/globalsign/mgo).
 
-A [sub-package](https://godoc.org/github.com/globalsign/mgo/bson) that implements [BSON](http://bsonspec.org) is also included, and may be used independently of the driver.
+A [sub-package](https://godoc.org/github.com/globalsign/mgo/bson) that implements the [BSON](http://bsonspec.org) specification is also included, and may be used independently of the driver.
 
 ## Changes
 * Fixes attempting to authenticate before every query ([details](https://github.com/go-mgo/mgo/issues/254))
@@ -46,25 +43,37 @@ A [sub-package](https://godoc.org/github.com/globalsign/mgo/bson) that implement
 * Use JSON tags when no explicit BSON are tags set ([details](https://github.com/globalsign/mgo/pull/91))
 * Support [$changeStream](https://docs.mongodb.com/manual/changeStreams/) tailing on 3.6+ ([details](https://github.com/globalsign/mgo/pull/97))
 * Fix deadlock in cluster synchronisation ([details](https://github.com/globalsign/mgo/issues/120))
+* Implement `maxIdleTimeout` for pooled connections ([details](https://github.com/globalsign/mgo/pull/116))
+* Connection pool waiting improvements ([details](https://github.com/globalsign/mgo/pull/115))
+* Fixes BSON encoding for `$in` and friends ([details](https://github.com/globalsign/mgo/pull/128))
+* Add BSON stream encoders ([details](https://github.com/globalsign/mgo/pull/127))
+* Add integer map key support in the BSON encoder ([details](https://github.com/globalsign/mgo/pull/140)) 
+* Support aggregation [collations](https://docs.mongodb.com/manual/reference/collation/) ([details](https://github.com/globalsign/mgo/pull/144))
 
 ---
 
 ### Thanks to
+* @aksentyev
 * @bachue
 * @bozaro
 * @BenLubar
+* @carldunham
 * @carter2000
 * @cezarsa
 * @drichelson
 * @dvic
 * @eaglerayp
 * @feliixx
 * @fmpwizard
+* @gazoon
+* @gnawux
 * @idy
 * @jameinel
+* @johnlawsharrison
 * @KJTsanaktsidis
-* @gazoon
 * @mapete94
+* @maxnoel
+* @mcspring
 * @peterdeka
 * @Reenjii
 * @smoya

bson/README.md

@@ -5,5 +5,8 @@ An Implementation of BSON for Go
 
 Package bson is an implementation of the [BSON specification](http://bsonspec.org) for Go.
 
-It was created as part of the mgo MongoDB driver for Go, but is standalone
-and may be used on its own without the driver.
+While the BSON package implements the BSON spec as faithfully as possible, there
+is some MongoDB specific behaviour (such as map keys `$in`, `$all`, etc) in the
+`bson` package. The priority is for backwards compatibility for the `mgo`
+driver, though fixes for obviously buggy behaviour is welcome (and features, etc
+behind feature flags).

example_test.go

@@ -90,12 +90,12 @@ func ExampleCredential_x509Authentication() {
 
 func ExampleSession_concurrency() {
 	// This example shows the best practise for concurrent use of a mgo session.
-	// 
+	//
 	// Internally mgo maintains a connection pool, dialling new connections as
-	// required. 
-	// 
+	// required.
+	//
 	// Some general suggestions:
-	// 		- Define a struct holding the original session, database name and 
+	// 		- Define a struct holding the original session, database name and
 	// 			collection name instead of passing them explicitly.
 	// 		- Define an interface abstracting your data access instead of exposing
 	// 			mgo to your application code directly.
@@ -107,7 +107,7 @@ func ExampleSession_concurrency() {
 
 		// Copy the session - if needed this will dial a new connection which
 		// can later be reused.
-		// 
+		//
 		// Calling close returns the connection to the pool.
 		conn := session.Copy()
 		defer conn.Close()
@@ -133,4 +133,31 @@ func ExampleSession_concurrency() {
 	wg.Wait()
 
 	session.Close()
-}
+}
+
+func ExampleDial_usingSSL() {
+	// To connect via TLS/SSL (enforced for MongoDB Atlas for example) requires
+	// configuring the dialer to use a TLS connection:
+	url := "mongodb://localhost:40003"
+
+	tlsConfig := &tls.Config{
+		// This can be configured to use a private root CA - see the Credential
+		// x509 Authentication example.
+		//
+		// Please don't set InsecureSkipVerify to true - it makes using TLS
+		// pointless and is never the right answer!
+	}
+
+	dialInfo, err := ParseURL(url)
+	dialInfo.DialServer = func(addr *ServerAddr) (net.Conn, error) {
+		return tls.Dial("tcp", addr.String(), tlsConfig)
+	}
+
+	session, err := DialWithInfo(dialInfo)
+	if err != nil {
+		panic(err)
+	}
+
+	// Use session as normal
+	session.Close()
+}