Merge lp:~rogpeppe/mgo/thread-safe-newobject into lp:mgo

[Roger Peppe]

bson: make NewObjectId thread safe

Also use an array rather than a slice to
remove a few unnecessary bounds checks.

Unmerged revisions

196. By Roger Peppe on 2013-04-03

bson: make NewObjectId thread safe

195. By Gustavo Niemeyer on 2013-03-27

Other minor test fixes for 2.4.

194. By Gustavo Niemeyer on 2013-03-26

auth_test.go: fix expected auth error messages for 2.4

193. By Gustavo Niemeyer on 2013-03-26

supervisord.conf: drop startsecs for mongos

192. By Gustavo Niemeyer on 2013-02-27

Test direct connection to a replicaset server in unknown membership state.

191. By Gustavo Niemeyer on 2013-02-27

Allow direct connection to replica set member in unknown state.

190. By Gustavo Niemeyer on 2013-01-21

Fixed omitempty on float values, as reported by Otto Bretz.

189. By Gustavo Niemeyer on 2013-01-21

New bson.IsObjectIdHex function.

188. By Gustavo Niemeyer on 2013-01-21

In preparation for 2.4, which is coming with multiple new index types,
change the format of 2D indexes from "@foo" to "$2d:foo". Preserve
parsing of the old style for compatibility.

187. By Gustavo Niemeyer on 2013-01-21

Fix DialWithInfo so it dials to the standard MongoDB port if the address
doesn't inform one. Thanks to Mark Severson for reporting the issue.

=== added file '.bzrignore'
--- .bzrignore	1970-01-01 00:00:00 +0000
+++ .bzrignore	2013-04-03 09:16:27 +0000
@@ -0,0 +1,2 @@
+_*
+[856].out

=== added file 'LICENSE'
--- LICENSE	1970-01-01 00:00:00 +0000
+++ LICENSE	2013-04-03 09:16:27 +0000
@@ -0,0 +1,25 @@
+mgo - MongoDB driver for Go
+
+Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met: 
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer. 
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=== added file 'Makefile'
--- Makefile	1970-01-01 00:00:00 +0000
+++ Makefile	2013-04-03 09:16:27 +0000
@@ -0,0 +1,5 @@
+startdb:
+	@testdb/setup.sh start
+
+stopdb:
+	@testdb/setup.sh stop

=== added file 'auth.go'
--- auth.go	1970-01-01 00:00:00 +0000
+++ auth.go	2013-04-03 09:16:27 +0000
@@ -0,0 +1,276 @@
+// mgo - MongoDB driver for Go
+// 
+// Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+// 
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met: 
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this
+//    list of conditions and the following disclaimer. 
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution. 
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+package mgo
+
+import (
+	"crypto/md5"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"labix.org/v2/mgo/bson"
+	"sync"
+)
+
+type authInfo struct {
+	db, user, pass string
+}
+
+type authCmd struct {
+	Authenticate     int
+	Nonce, User, Key string
+}
+
+type authResult struct {
+	ErrMsg string
+	Ok     bool
+}
+
+type getNonceCmd struct {
+	GetNonce int
+}
+
+type getNonceResult struct {
+	Nonce string
+	Err   string "$err"
+	Code  int
+}
+
+type logoutCmd struct {
+	Logout int
+}
+
+func (socket *mongoSocket) getNonce() (nonce string, err error) {
+	socket.Lock()
+	for socket.cachedNonce == "" && socket.dead == nil {
+		debugf("Socket %p to %s: waiting for nonce", socket, socket.addr)
+		socket.gotNonce.Wait()
+	}
+	if socket.cachedNonce == "mongos" {
+		socket.Unlock()
+		return "", errors.New("Can't authenticate with mongos; see http://j.mp/mongos-auth")
+	}
+	debugf("Socket %p to %s: got nonce", socket, socket.addr)
+	nonce, err = socket.cachedNonce, socket.dead
+	socket.cachedNonce = ""
+	socket.Unlock()
+	if err != nil {
+		nonce = ""
+	}
+	return
+}
+
+func (socket *mongoSocket) resetNonce() {
+	debugf("Socket %p to %s: requesting a new nonce", socket, socket.addr)
+	op := &queryOp{}
+	op.query = &getNonceCmd{GetNonce: 1}
+	op.collection = "admin.$cmd"
+	op.limit = -1
+	op.replyFunc = func(err error, reply *replyOp, docNum int, docData []byte) {
+		if err != nil {
+			socket.kill(errors.New("getNonce: " + err.Error()), true)
+			return
+		}
+		result := &getNonceResult{}
+		err = bson.Unmarshal(docData, &result)
+		if err != nil {
+			socket.kill(errors.New("Failed to unmarshal nonce: " + err.Error()), true)
+			return
+		}
+		debugf("Socket %p to %s: nonce unmarshalled: %#v", socket, socket.addr, result)
+		if result.Code == 13390 {
+			// mongos doesn't yet support auth (see http://j.mp/mongos-auth)
+			result.Nonce = "mongos"
+		} else if result.Nonce == "" {
+			var msg string
+			if result.Err != "" {
+				msg = fmt.Sprintf("Got an empty nonce: %s (%d)", result.Err, result.Code)
+			} else {
+				msg = "Got an empty nonce"
+			}
+			socket.kill(errors.New(msg), true)
+			return
+		}
+		socket.Lock()
+		if socket.cachedNonce != "" {
+			socket.Unlock()
+			panic("resetNonce: nonce already cached")
+		}
+		socket.cachedNonce = result.Nonce
+		socket.gotNonce.Signal()
+		socket.Unlock()
+	}
+	err := socket.Query(op)
+	if err != nil {
+		socket.kill(errors.New("resetNonce: " + err.Error()), true)
+	}
+}
+
+func (socket *mongoSocket) Login(db string, user string, pass string) error {
+	socket.Lock()
+	for _, a := range socket.auth {
+		if a.db == db && a.user == user && a.pass == pass {
+			debugf("Socket %p to %s: login: db=%q user=%q (already logged in)", socket, socket.addr, db, user)
+			socket.Unlock()
+			return nil
+		}
+	}
+	if auth, found := socket.dropLogout(db, user, pass); found {
+		debugf("Socket %p to %s: login: db=%q user=%q (cached)", socket, socket.addr, db, user)
+		socket.auth = append(socket.auth, auth)
+		socket.Unlock()
+		return nil
+	}
+	socket.Unlock()
+
+	debugf("Socket %p to %s: login: db=%q user=%q", socket, socket.addr, db, user)
+
+	// Note that this only works properly because this function is
+	// synchronous, which means the nonce won't get reset while we're
+	// using it and any other login requests will block waiting for a
+	// new nonce provided in the defer call below.
+	nonce, err := socket.getNonce()
+	if err != nil {
+		return err
+	}
+	defer socket.resetNonce()
+
+	psum := md5.New()
+	psum.Write([]byte(user + ":mongo:" + pass))
+
+	ksum := md5.New()
+	ksum.Write([]byte(nonce + user))
+	ksum.Write([]byte(hex.EncodeToString(psum.Sum(nil))))
+
+	key := hex.EncodeToString(ksum.Sum(nil))
+
+	cmd := authCmd{Authenticate: 1, User: user, Nonce: nonce, Key: key}
+
+	var mutex sync.Mutex
+	var replyErr error
+	mutex.Lock()
+
+	op := queryOp{}
+	op.query = &cmd
+	op.collection = db + ".$cmd"
+	op.limit = -1
+	op.replyFunc = func(err error, reply *replyOp, docNum int, docData []byte) {
+		defer mutex.Unlock()
+
+		if err != nil {
+			replyErr = err
+			return
+		}
+
+		// Must handle this within the read loop for the socket, so
+		// that concurrent login requests are properly ordered.
+		result := &authResult{}
+		err = bson.Unmarshal(docData, result)
+		if err != nil {
+			replyErr = err
+			return
+		}
+		if !result.Ok {
+			replyErr = errors.New(result.ErrMsg)
+		}
+
+		socket.Lock()
+		socket.dropAuth(db)
+		socket.auth = append(socket.auth, authInfo{db, user, pass})
+		socket.Unlock()
+	}
+
+	err = socket.Query(&op)
+	if err != nil {
+		return err
+	}
+	mutex.Lock() // Wait.
+	if replyErr != nil {
+		debugf("Socket %p to %s: login error: %s", socket, socket.addr, replyErr)
+	} else {
+		debugf("Socket %p to %s: login successful", socket, socket.addr)
+	}
+	return replyErr
+}
+
+func (socket *mongoSocket) Logout(db string) {
+	socket.Lock()
+	auth, found := socket.dropAuth(db)
+	if found {
+		debugf("Socket %p to %s: logout: db=%q (flagged)", socket, socket.addr, db)
+		socket.logout = append(socket.logout, auth)
+	}
+	socket.Unlock()
+}
+
+func (socket *mongoSocket) LogoutAll() {
+	socket.Lock()
+	if l := len(socket.auth); l > 0 {
+		debugf("Socket %p to %s: logout all (flagged %d)", socket, socket.addr, l)
+		socket.logout = append(socket.logout, socket.auth...)
+		socket.auth = socket.auth[0:0]
+	}
+	socket.Unlock()
+}
+
+func (socket *mongoSocket) flushLogout() (ops []interface{}) {
+	socket.Lock()
+	if l := len(socket.logout); l > 0 {
+		debugf("Socket %p to %s: logout all (flushing %d)", socket, socket.addr, l)
+		for i := 0; i != l; i++ {
+			op := queryOp{}
+			op.query = &logoutCmd{1}
+			op.collection = socket.logout[i].db + ".$cmd"
+			op.limit = -1
+			ops = append(ops, &op)
+		}
+		socket.logout = socket.logout[0:0]
+	}
+	socket.Unlock()
+	return
+}
+
+func (socket *mongoSocket) dropAuth(db string) (auth authInfo, found bool) {
+	for i, a := range socket.auth {
+		if a.db == db {
+			copy(socket.auth[i:], socket.auth[i+1:])
+			socket.auth = socket.auth[:len(socket.auth)-1]
+			return a, true
+		}
+	}
+	return auth, false
+}
+
+func (socket *mongoSocket) dropLogout(db, user, pass string) (auth authInfo, found bool) {
+	for i, a := range socket.logout {
+		if a.db == db && a.user == user && a.pass == pass {
+			copy(socket.logout[i:], socket.logout[i+1:])
+			socket.logout = socket.logout[:len(socket.logout)-1]
+			return a, true
+		}
+	}
+	return auth, false
+}

=== added file 'auth_test.go'
--- auth_test.go	1970-01-01 00:00:00 +0000
+++ auth_test.go	2013-04-03 09:16:27 +0000
@@ -0,0 +1,560 @@
+// mgo - MongoDB driver for Go
+// 
+// Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+// 
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met: 
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this
+//    list of conditions and the following disclaimer. 
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution. 
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+package mgo_test
+
+import (
+	. "launchpad.net/gocheck"
+	"labix.org/v2/mgo"
+	"sync"
+)
+
+func (s *S) TestAuthLogin(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|need to login|not authorized .*")
+
+	admindb := session.DB("admin")
+
+	err = admindb.Login("root", "wrong")
+	c.Assert(err, ErrorMatches, "auth fails")
+
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+}
+
+func (s *S) TestAuthLoginLogout(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	admindb.Logout()
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|need to login|not authorized .*")
+
+	// Must have dropped auth from the session too.
+	session = session.Copy()
+	defer session.Close()
+
+	coll = session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|need to login|not authorized .*")
+}
+
+func (s *S) TestAuthLoginLogoutAll(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	session.LogoutAll()
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|need to login|not authorized .*")
+
+	// Must have dropped auth from the session too.
+	session = session.Copy()
+	defer session.Close()
+
+	coll = session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|need to login|not authorized .*")
+}
+
+func (s *S) TestAuthAddUser(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	mydb := session.DB("mydb")
+	err = mydb.AddUser("myruser", "mypass", true)
+	c.Assert(err, IsNil)
+	err = mydb.AddUser("mywuser", "mypass", false)
+	c.Assert(err, IsNil)
+
+	err = mydb.Login("myruser", "mypass")
+	c.Assert(err, IsNil)
+
+	admindb.Logout()
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|not authorized .*")
+
+	err = mydb.Login("mywuser", "mypass")
+	c.Assert(err, IsNil)
+
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+}
+
+func (s *S) TestAuthAddUserReplaces(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	mydb := session.DB("mydb")
+	err = mydb.AddUser("myuser", "myoldpass", false)
+	c.Assert(err, IsNil)
+	err = mydb.AddUser("myuser", "mynewpass", true)
+	c.Assert(err, IsNil)
+
+	admindb.Logout()
+
+	err = mydb.Login("myuser", "myoldpass")
+	c.Assert(err, ErrorMatches, "auth fails")
+	err = mydb.Login("myuser", "mynewpass")
+	c.Assert(err, IsNil)
+
+	// ReadOnly flag was changed too.
+	err = mydb.C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|not authorized .*")
+}
+
+func (s *S) TestAuthRemoveUser(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	mydb := session.DB("mydb")
+	err = mydb.AddUser("myuser", "mypass", true)
+	c.Assert(err, IsNil)
+	err = mydb.RemoveUser("myuser")
+	c.Assert(err, IsNil)
+
+	err = mydb.Login("myuser", "mypass")
+	c.Assert(err, ErrorMatches, "auth fails")
+}
+
+func (s *S) TestAuthLoginTwiceDoesNothing(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	oldStats := mgo.GetStats()
+
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	newStats := mgo.GetStats()
+	c.Assert(newStats.SentOps, Equals, oldStats.SentOps)
+}
+
+func (s *S) TestAuthLoginLogoutLoginDoesNothing(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	oldStats := mgo.GetStats()
+
+	admindb.Logout()
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	newStats := mgo.GetStats()
+	c.Assert(newStats.SentOps, Equals, oldStats.SentOps)
+}
+
+func (s *S) TestAuthLoginSwitchUser(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+
+	err = admindb.Login("reader", "rapadura")
+	c.Assert(err, IsNil)
+
+	// Can't write.
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|not authorized .*")
+
+	// But can read.
+	result := struct{ N int }{}
+	err = coll.Find(nil).One(&result)
+	c.Assert(err, IsNil)
+	c.Assert(result.N, Equals, 1)
+}
+
+func (s *S) TestAuthLoginChangePassword(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	mydb := session.DB("mydb")
+	err = mydb.AddUser("myuser", "myoldpass", false)
+	c.Assert(err, IsNil)
+
+	err = mydb.Login("myuser", "myoldpass")
+	c.Assert(err, IsNil)
+
+	err = mydb.AddUser("myuser", "mynewpass", true)
+	c.Assert(err, IsNil)
+
+	err = mydb.Login("myuser", "mynewpass")
+	c.Assert(err, IsNil)
+
+	admindb.Logout()
+
+	// The second login must be in effect, which means read-only.
+	err = mydb.C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|not authorized .*")
+}
+
+func (s *S) TestAuthLoginCachingWithSessionRefresh(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	session.Refresh()
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+}
+
+func (s *S) TestAuthLoginCachingWithSessionCopy(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	session = session.Copy()
+	defer session.Close()
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+}
+
+func (s *S) TestAuthLoginCachingWithSessionClone(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	session = session.Clone()
+	defer session.Close()
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+}
+
+func (s *S) TestAuthLoginCachingWithNewSession(c *C) {
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	session = session.New()
+	defer session.Close()
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|need to login|not authorized for .*")
+}
+
+func (s *S) TestAuthLoginCachingAcrossPool(c *C) {
+	// Logins are cached even when the conenction goes back
+	// into the pool.
+
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	// Add another user to test the logout case at the same time.
+	mydb := session.DB("mydb")
+	err = mydb.AddUser("myuser", "mypass", false)
+	c.Assert(err, IsNil)
+
+	err = mydb.Login("myuser", "mypass")
+	c.Assert(err, IsNil)
+
+	// Logout root explicitly, to test both cases.
+	admindb.Logout()
+
+	// Give socket back to pool.
+	session.Refresh()
+
+	// Brand new session, should use socket from the pool.
+	other := session.New()
+	defer other.Close()
+
+	oldStats := mgo.GetStats()
+
+	err = other.DB("admin").Login("root", "rapadura")
+	c.Assert(err, IsNil)
+	err = other.DB("mydb").Login("myuser", "mypass")
+	c.Assert(err, IsNil)
+
+	// Both logins were cached, so no ops.
+	newStats := mgo.GetStats()
+	c.Assert(newStats.SentOps, Equals, oldStats.SentOps)
+
+	// And they actually worked.
+	err = other.DB("mydb").C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+
+	other.DB("admin").Logout()
+
+	err = other.DB("mydb").C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+}
+
+func (s *S) TestAuthLoginCachingAcrossPoolWithLogout(c *C) {
+	// Now verify that logouts are properly flushed if they
+	// are not revalidated after leaving the pool.
+
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	// Add another user to test the logout case at the same time.
+	mydb := session.DB("mydb")
+	err = mydb.AddUser("myuser", "mypass", true)
+	c.Assert(err, IsNil)
+
+	err = mydb.Login("myuser", "mypass")
+	c.Assert(err, IsNil)
+
+	// Just some data to query later.
+	err = session.DB("mydb").C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+
+	// Give socket back to pool.
+	session.Refresh()
+
+	// Brand new session, should use socket from the pool.
+	other := session.New()
+	defer other.Close()
+
+	oldStats := mgo.GetStats()
+
+	err = other.DB("mydb").Login("myuser", "mypass")
+	c.Assert(err, IsNil)
+
+	// Login was cached, so no ops.
+	newStats := mgo.GetStats()
+	c.Assert(newStats.SentOps, Equals, oldStats.SentOps)
+
+	// Can't write, since root has been implicitly logged out
+	// when the collection went into the pool, and not revalidated.
+	err = other.DB("mydb").C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|not authorized .*")
+
+	// But can read due to the revalidated myuser login.
+	result := struct{ N int }{}
+	err = other.DB("mydb").C("mycoll").Find(nil).One(&result)
+	c.Assert(err, IsNil)
+	c.Assert(result.N, Equals, 1)
+}
+
+func (s *S) TestAuthEventual(c *C) {
+	// Eventual sessions don't keep sockets around, so they are
+	// an interesting test case.
+	session, err := mgo.Dial("localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	admindb := session.DB("admin")
+	err = admindb.Login("root", "rapadura")
+	c.Assert(err, IsNil)
+
+	err = session.DB("mydb").C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+
+	var wg sync.WaitGroup
+	wg.Add(20)
+
+	for i := 0; i != 10; i++ {
+		go func() {
+			defer wg.Done()
+			var result struct{ N int }
+			err := session.DB("mydb").C("mycoll").Find(nil).One(&result)
+			c.Assert(err, IsNil)
+			c.Assert(result.N, Equals, 1)
+		}()
+	}
+
+	for i := 0; i != 10; i++ {
+		go func() {
+			defer wg.Done()
+			err := session.DB("mydb").C("mycoll").Insert(M{"n": 1})
+			c.Assert(err, IsNil)
+		}()
+	}
+
+	wg.Wait()
+}
+
+func (s *S) TestAuthURL(c *C) {
+	session, err := mgo.Dial("mongodb://root:rapadura@localhost:40002/")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	err = session.DB("mydb").C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+}
+
+func (s *S) TestAuthURLWrongCredentials(c *C) {
+	session, err := mgo.Dial("mongodb://root:wrong@localhost:40002/")
+	if session != nil {
+		session.Close()
+	}
+	c.Assert(err, ErrorMatches, "auth fails")
+	c.Assert(session, IsNil)
+}
+
+func (s *S) TestAuthURLWithNewSession(c *C) {
+	// When authentication is in the URL, the new session will
+	// actually carry it on as well, even if logged out explicitly.
+	session, err := mgo.Dial("mongodb://root:rapadura@localhost:40002/")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	session.DB("admin").Logout()
+
+	// Do it twice to ensure it passes the needed data on.
+	session = session.New()
+	defer session.Close()
+	session = session.New()
+	defer session.Close()
+
+	err = session.DB("mydb").C("mycoll").Insert(M{"n": 1})
+	c.Assert(err, IsNil)
+}
+
+func (s *S) TestAuthURLWithDatabase(c *C) {
+	session, err := mgo.Dial("mongodb://root:rapadura@localhost:40002")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	mydb := session.DB("mydb")
+	err = mydb.AddUser("myruser", "mypass", true)
+	c.Assert(err, IsNil)
+
+	usession, err := mgo.Dial("mongodb://myruser:mypass@localhost:40002/mydb")
+	c.Assert(err, IsNil)
+	defer usession.Close()
+
+	ucoll := usession.DB("mydb").C("mycoll")
+	err = ucoll.FindId(0).One(nil)
+	c.Assert(err, Equals, mgo.ErrNotFound)
+	err = ucoll.Insert(M{"n": 1})
+	c.Assert(err, ErrorMatches, "unauthorized|not authorized .*")
+}
+
+func (s *S) TestDefaultDatabase(c *C) {
+	tests := []struct{ url, db string }{
+		{"mongodb://root:rapadura@localhost:40002", "test"},
+		{"mongodb://root:rapadura@localhost:40002/admin", "admin"},
+		{"mongodb://localhost:40001", "test"},
+		{"mongodb://localhost:40001/", "test"},
+		{"mongodb://localhost:40001/mydb", "mydb"},
+	}
+
+	for _, test := range tests {
+		session, err := mgo.Dial(test.url)
+		c.Assert(err, IsNil)
+		defer session.Close()
+
+		c.Logf("test: %#v", test)
+		c.Assert(session.DB("").Name, Equals, test.db)
+
+		scopy := session.Copy()
+		c.Check(scopy.DB("").Name, Equals, test.db)
+		scopy.Close()
+	}
+}

=== added directory 'bson'
=== renamed directory 'bson' => 'bson.moved'
=== added file 'bson/LICENSE'
--- bson/LICENSE	1970-01-01 00:00:00 +0000
+++ bson/LICENSE	2013-04-03 09:16:27 +0000
@@ -0,0 +1,25 @@
+BSON library for Go
+
+Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met: 
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer. 
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=== added file 'bson/bson.go'
--- bson/bson.go	1970-01-01 00:00:00 +0000
+++ bson/bson.go	2013-04-03 09:16:27 +0000
@@ -0,0 +1,639 @@
+// BSON library for Go
+// 
+// Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+// 
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met: 
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this
+//    list of conditions and the following disclaimer. 
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution. 
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+package bson
+
+import (
+	"crypto/md5"
+	"crypto/rand"
+	"encoding/binary"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"reflect"
+	"runtime"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// --------------------------------------------------------------------------
+// The public API.
+
+// A value implementing the bson.Getter interface will have its GetBSON
+// method called when the given value has to be marshalled, and the result
+// of this method will be marshaled in place of the actual object.
+//
+// If GetBSON returns return a non-nil error, the marshalling procedure
+// will stop and error out with the provided value.
+type Getter interface {
+	GetBSON() (interface{}, error)
+}
+
+// A value implementing the bson.Setter interface will receive the BSON
+// value via the SetBSON method during unmarshaling, and the object
+// itself will not be changed as usual.
+//
+// If setting the value works, the method should return nil or alternatively
+// bson.SetZero to set the respective field to its zero value (nil for
+// pointer types). If SetBSON returns a value of type bson.TypeError, the
+// BSON value will be omitted from a map or slice being decoded and the
+// unmarshalling will continue. If it returns any other non-nil error, the
+// unmarshalling procedure will stop and error out with the provided value.
+//
+// This interface is generally useful in pointer receivers, since the method
+// will want to change the receiver. A type field that implements the Setter
+// interface doesn't have to be a pointer, though.
+//
+// Unlike the usual behavior, unmarshalling onto a value that implements a
+// Setter interface will NOT reset the value to its zero state. This allows
+// the value to decide by itself how to be unmarshalled.
+//
+// For example:
+//
+//     type MyString string
+//
+//     func (s *MyString) SetBSON(raw bson.Raw) error {
+//         return raw.Unmarshal(s)
+//     }
+//
+type Setter interface {
+	SetBSON(raw Raw) error
+}
+
+// SetZero may be returned from a SetBSON method to have the value set to
+// its respective zero value. When used in pointer values, this will set the
+// field to nil rather than to the pre-allocated value.
+var SetZero = errors.New("set to zero")
+
+// M is a convenient alias for a map[string]interface{} map, useful for
+// dealing with BSON in a native way.  For instance:
+//
+//     bson.M{"a": 1, "b": true}
+//
+// There's no special handling for this type in addition to what's done anyway
+// for an equivalent map type.  Elements in the map will be dumped in an
+// undefined ordered. See also the bson.D type for an ordered alternative.
+type M map[string]interface{}
+
+// D is a type for dealing with documents containing ordered elements in a
+// native fashion. For instance:
+//
+//     bson.D{{"a", 1}, {"b", true}}
+//
+// In some situations, such as when creating indexes for MongoDB, the order in
+// which the elements are defined is important.  If the order is not important,
+// using a map is generally more comfortable. See the bson.M type and the
+// Map() method for D.
+type D []DocElem
+
+// See the bson.D type.
+type DocElem struct {
+	Name  string
+	Value interface{}
+}
+
+// The Raw type represents raw unprocessed BSON documents and elements.
+// Kind is the kind of element as defined per the BSON specification, and
+// Data is the raw unprocessed data for the respective element.
+// Using this type it is possible to unmarshal or marshal values partially.
+//
+// Relevant documentation:
+//
+//     http://bsonspec.org/#/specification
+//
+type Raw struct {
+	Kind byte
+	Data []byte
+}
+
+// Map returns a map out of the ordered element name/value pairs in d.
+func (d D) Map() (m M) {
+	m = make(M, len(d))
+	for _, item := range d {
+		m[item.Name] = item.Value
+	}
+	return m
+}
+
+// ObjectId is a unique ID identifying a BSON value. It must be exactly 12 bytes
+// long. MongoDB objects by default have such a property set in their "_id"
+// property.
+//
+// http://www.mongodb.org/display/DOCS/Object+IDs
+type ObjectId string
+
+// ObjectIdHex returns an ObjectId from the provided hex representation.
+// Calling this function with an invalid hex representation will
+// cause a runtime panic. See the IsObjectIdHex function.
+func ObjectIdHex(s string) ObjectId {
+	d, err := hex.DecodeString(s)
+	if err != nil || len(d) != 12 {
+		panic(fmt.Sprintf("Invalid input to ObjectIdHex: %q", s))
+	}
+	return ObjectId(d)
+}
+
+// IsObjectIdHex returns whether s is a valid hex representation of
+// an ObjectId. See the ObjectIdHex function.
+func IsObjectIdHex(s string) bool {
+	if len(s) != 24 {
+		return false
+	}
+	_, err := hex.DecodeString(s)
+	return err == nil
+}
+
+// objectIdCounter is atomically incremented when generating a new ObjectId
+// using NewObjectId() function. It's used as a counter part of an id.
+var objectIdCounter uint32 = 0
+
+// machineId stores machine id generated once and used in subsequent calls
+// to NewObjectId function.
+var machineId = readMachineId()
+
+// initMachineId generates machine id and puts it into the machineId global
+// variable. If this function fails to get the hostname, it will cause
+// a runtime error.
+func readMachineId() []byte {
+	var sum [3]byte
+	id := sum[:]
+	hostname, err1 := os.Hostname()
+	if err1 != nil {
+		_, err2 := io.ReadFull(rand.Reader, id)
+		if err2 != nil {
+			panic(fmt.Errorf("cannot get hostname: %v; %v", err1, err2))
+		}
+		return id
+	}
+	hw := md5.New()
+	hw.Write([]byte(hostname))
+	copy(id, hw.Sum(nil))
+	return id
+}
+
+// NewObjectId returns a new unique ObjectId.
+// This function causes a runtime error if it fails to get the hostname
+// of the current machine.
+func NewObjectId() ObjectId {
+	var b [12]byte
+	// Timestamp, 4 bytes, big endian
+	binary.BigEndian.PutUint32(b[:], uint32(time.Now().Unix()))
+	// Machine, first 3 bytes of md5(hostname)
+	b[4] = machineId[0]
+	b[5] = machineId[1]
+	b[6] = machineId[2]
+	// Pid, 2 bytes, specs don't specify endianness, but we use big endian.
+	pid := os.Getpid()
+	b[7] = byte(pid >> 8)
+	b[8] = byte(pid)
+	// Increment, 3 bytes, big endian
+	i := atomic.AddUint32(&objectIdCounter, 1)
+	b[9] = byte(i >> 16)
+	b[10] = byte(i >> 8)
+	b[11] = byte(i)
+	return ObjectId(b[:])
+}
+
+// NewObjectIdWithTime returns a dummy ObjectId with the timestamp part filled
+// with the provided number of seconds from epoch UTC, and all other parts
+// filled with zeroes. It's not safe to insert a document with an id generated
+// by this method, it is useful only for queries to find documents with ids
+// generated before or after the specified timestamp.
+func NewObjectIdWithTime(t time.Time) ObjectId {
+	var b [12]byte
+	binary.BigEndian.PutUint32(b[:4], uint32(t.Unix()))
+	return ObjectId(string(b[:]))
+}
+
+// String returns a hex string representation of the id.
+// Example: ObjectIdHex("4d88e15b60f486e428412dc9").
+func (id ObjectId) String() string {
+	return fmt.Sprintf(`ObjectIdHex("%x")`, string(id))
+}
+
+// Hex returns a hex representation of the ObjectId.
+func (id ObjectId) Hex() string {
+	return hex.EncodeToString([]byte(id))
+}
+
+// MarshalJSON turns a bson.ObjectId into a json.Marshaller.
+func (id ObjectId) MarshalJSON() ([]byte, error) {
+	return []byte(fmt.Sprintf(`"%x"`, string(id))), nil
+}
+
+// UnmarshalJSON turns *bson.ObjectId into a json.Unmarshaller.
+func (id *ObjectId) UnmarshalJSON(data []byte) error {
+	if len(data) != 26 || data[0] != '"' || data[25] != '"' {
+		return errors.New(fmt.Sprintf("Invalid ObjectId in JSON: %s", string(data)))
+	}
+	var buf [12]byte
+	_, err := hex.Decode(buf[:], data[1:25])
+	if err != nil {
+		return errors.New(fmt.Sprintf("Invalid ObjectId in JSON: %s (%s)", string(data), err))
+	}
+	*id = ObjectId(string(buf[:]))
+	return nil
+}
+
+// Valid returns true if id is valid. A valid id must contain exactly 12 bytes.
+func (id ObjectId) Valid() bool {
+	return len(id) == 12
+}
+
+// byteSlice returns byte slice of id from start to end.
+// Calling this function with an invalid id will cause a runtime panic.
+func (id ObjectId) byteSlice(start, end int) []byte {
+	if len(id) != 12 {
+		panic(fmt.Sprintf("Invalid ObjectId: %q", string(id)))
+	}
+	return []byte(string(id)[start:end])
+}
+
+// Time returns the timestamp part of the id.
+// It's a runtime error to call this method with an invalid id.
+func (id ObjectId) Time() time.Time {
+	// First 4 bytes of ObjectId is 32-bit big-endian seconds from epoch.
+	secs := int64(binary.BigEndian.Uint32(id.byteSlice(0, 4)))
+	return time.Unix(secs, 0)
+}
+
+// Machine returns the 3-byte machine id part of the id.
+// It's a runtime error to call this method with an invalid id.
+func (id ObjectId) Machine() []byte {
+	return id.byteSlice(4, 7)
+}
+
+// Pid returns the process id part of the id.
+// It's a runtime error to call this method with an invalid id.
+func (id ObjectId) Pid() uint16 {
+	return binary.BigEndian.Uint16(id.byteSlice(7, 9))
+}
+
+// Counter returns the incrementing value part of the id.
+// It's a runtime error to call this method with an invalid id.
+func (id ObjectId) Counter() int32 {
+	b := id.byteSlice(9, 12)
+	// Counter is stored as big-endian 3-byte value
+	return int32(uint32(b[0])<<16 | uint32(b[1])<<8 | uint32(b[2]))
+}
+
+// The Symbol type is similar to a string and is used in languages with a
+// distinct symbol type.
+type Symbol string
+
+// Now returns the current time with millisecond precision. MongoDB stores
+// timestamps with the same precision, so a Time returned from this method
+// will not change after a roundtrip to the database. That's the only reason
+// why this function exists. Using the time.Now function also works fine
+// otherwise.
+func Now() time.Time {
+	return time.Unix(0, time.Now().UnixNano()/1e6*1e6)
+}
+
+// MongoTimestamp is a special internal type used by MongoDB that for some
+// strange reason has its own datatype defined in BSON.
+type MongoTimestamp int64
+
+type orderKey int64
+
+// MaxKey is a special value that compares higher than all other possible BSON
+// values in a MongoDB database.
+var MaxKey = orderKey(1<<63 - 1)
+
+// MinKey is a special value that compares lower than all other possible BSON
+// values in a MongoDB database.
+var MinKey = orderKey(-1 << 63)
+
+type undefined struct{}
+
+// Undefined represents the undefined BSON value.
+var Undefined undefined
+
+// Binary is a representation for non-standard binary values.  Any kind should
+// work, but the following are known as of this writing:
+//
+//   0x00 - Generic. This is decoded as []byte(data), not Binary{0x00, data}.
+//   0x01 - Function (!?)
+//   0x02 - Obsolete generic.
+//   0x03 - UUID
+//   0x05 - MD5
+//   0x80 - User defined.
+//
+type Binary struct {
+	Kind byte
+	Data []byte
+}
+
+// RegEx represents a regular expression.  The Options field may contain
+// individual characters defining the way in which the pattern should be
+// applied, and must be sorted. Valid options as of this writing are 'i' for
+// case insensitive matching, 'm' for multi-line matching, 'x' for verbose
+// mode, 'l' to make \w, \W, and similar be locale-dependent, 's' for dot-all
+// mode (a '.' matches everything), and 'u' to make \w, \W, and similar match
+// unicode. The value of the Options parameter is not verified before being
+// marshaled into the BSON format.
+type RegEx struct {
+	Pattern string
+	Options string
+}
+
+// JavaScript is a type that holds JavaScript code. If Scope is non-nil, it
+// will be marshaled as a mapping from identifiers to values that may be
+// used when evaluating the provided Code.
+type JavaScript struct {
+	Code  string
+	Scope interface{}
+}
+
+const initialBufferSize = 64
+
+func handleErr(err *error) {
+	if r := recover(); r != nil {
+		if _, ok := r.(runtime.Error); ok {
+			panic(r)
+		} else if _, ok := r.(externalPanic); ok {
+			panic(r)
+		} else if s, ok := r.(string); ok {
+			*err = errors.New(s)
+		} else if e, ok := r.(error); ok {
+			*err = e
+		} else {
+			panic(r)
+		}
+	}
+}
+
+// Marshal serializes the in value, which may be a map or a struct value.
+// In the case of struct values, only exported fields will be serialized.
+// The lowercased field name is used as the key for each exported field,
+// but this behavior may be changed using the respective field tag.
+// The tag may also contain flags to tweak the marshalling behavior for
+// the field. The tag formats accepted are:
+//
+//     "[<key>][,<flag1>[,<flag2>]]"
+//
+//     `(...) bson:"[<key>][,<flag1>[,<flag2>]]" (...)`
+//
+// The following flags are currently supported:
+//
+//     omitempty    Only include the field if it's not set to the zero
+//                  value for the type or to empty slices or maps.
+//                  Does not apply to zero valued structs.
+//
+//     minsize      Marshal an int64 value as an int32, if that's feasible
+//                  while preserving the numeric value.
+//
+//     inline       Inline the field, which must be a struct, causing all
+//                  of its fields to be processed as if they were part of
+//                  the outer struct.
+//
+// Some examples:
+//
+//     type T struct {
+//         A bool
+//         B int    "myb"
+//         C string "myc,omitempty"
+//         D string `bson:",omitempty" json:"jsonkey"`
+//         E int64  ",minsize"
+//         F int64  "myf,omitempty,minsize"
+//     }
+//           
+func Marshal(in interface{}) (out []byte, err error) {
+	defer handleErr(&err)
+	e := &encoder{make([]byte, 0, initialBufferSize)}
+	e.addDoc(reflect.ValueOf(in))
+	return e.out, nil
+}
+
+// Unmarshal deserializes data from in into the out value.  The out value
+// must be a map, a pointer to a struct, or a pointer to a bson.D value.
+// The lowercased field name is used as the key for each exported field,
+// but this behavior may be changed using the respective field tag.
+// Pointer values are initialized when necessary.
+//
+// The target field or element types of out may not necessarily match
+// the BSON values of the provided data.  The following conversions are
+// made automatically:
+//
+// - Numeric types are converted if at least the integer part of the
+//   value would be preserved correctly
+// - Bools are converted to numeric types as 1 or 0
+// - Numeric types are converted to bools as true if not 0 or false otherwise
+// - Binary and string BSON data is converted to a string, array or byte slice
+//
+// If the value would not fit the type and cannot be converted, it's silently
+// skipped.
+func Unmarshal(in []byte, out interface{}) (err error) {
+	defer handleErr(&err)
+	v := reflect.ValueOf(out)
+	switch v.Kind() {
+	case reflect.Map, reflect.Ptr:
+		d := newDecoder(in)
+		d.readDocTo(v)
+	case reflect.Struct:
+		return errors.New("Unmarshal can't deal with struct values. Use a pointer.")
+	default:
+		return errors.New("Unmarshal needs a map or a pointer to a struct.")
+	}
+	return nil
+}
+
+// Unmarshal deserializes raw into the out value.  If the out value type
+// is not compatible with raw, a *bson.TypeError is returned.
+//
+// See the Unmarshal function documentation for more details on the
+// unmarshalling process.
+func (raw Raw) Unmarshal(out interface{}) (err error) {
+	defer handleErr(&err)
+	v := reflect.ValueOf(out)
+	switch v.Kind() {
+	case reflect.Ptr:
+		v = v.Elem()
+		fallthrough
+	case reflect.Map:
+		d := newDecoder(raw.Data)
+		good := d.readElemTo(v, raw.Kind)
+		if !good {
+			return &TypeError{v.Type(), raw.Kind}
+		}
+	case reflect.Struct:
+		return errors.New("Raw Unmarshal can't deal with struct values. Use a pointer.")
+	default:
+		return errors.New("Raw Unmarshal needs a map or a valid pointer.")
+	}
+	return nil
+}
+
+type TypeError struct {
+	Type reflect.Type
+	Kind byte
+}
+
+func (e *TypeError) Error() string {
+	return fmt.Sprintf("BSON kind 0x%02x isn't compatible with type %s", e.Kind, e.Type.String())
+}
+
+// --------------------------------------------------------------------------
+// Maintain a mapping of keys to structure field indexes
+
+type structInfo struct {
+	FieldsMap  map[string]fieldInfo
+	FieldsList []fieldInfo
+	Zero       reflect.Value
+}
+
+type fieldInfo struct {
+	Key       string
+	Num       int
+	OmitEmpty bool
+	MinSize   bool
+	Inline    []int
+}
+
+var structMap = make(map[reflect.Type]*structInfo)
+var structMapMutex sync.RWMutex
+
+type externalPanic string
+
+func (e externalPanic) String() string {
+	return string(e)
+}
+
+func getStructInfo(st reflect.Type) (*structInfo, error) {
+	structMapMutex.RLock()
+	sinfo, found := structMap[st]
+	structMapMutex.RUnlock()
+	if found {
+		return sinfo, nil
+	}
+	n := st.NumField()
+	fieldsMap := make(map[string]fieldInfo)
+	fieldsList := make([]fieldInfo, 0, n)
+	for i := 0; i != n; i++ {
+		field := st.Field(i)
+		if field.PkgPath != "" {
+			continue // Private field
+		}
+
+		info := fieldInfo{Num: i}
+
+		tag := field.Tag.Get("bson")
+		if tag == "" && strings.Index(string(field.Tag), ":") < 0 {
+			tag = string(field.Tag)
+		}
+		if tag == "-" {
+			continue
+		}
+
+		// XXX Drop this after a few releases.
+		if s := strings.Index(tag, "/"); s >= 0 {
+			recommend := tag[:s]
+			for _, c := range tag[s+1:] {
+				switch c {
+				case 'c':
+					recommend += ",omitempty"
+				case 's':
+					recommend += ",minsize"
+				default:
+					msg := fmt.Sprintf("Unsupported flag %q in tag %q of type %s", string([]byte{uint8(c)}), tag, st)
+					panic(externalPanic(msg))
+				}
+			}
+			msg := fmt.Sprintf("Replace tag %q in field %s of type %s by %q", tag, field.Name, st, recommend)
+			panic(externalPanic(msg))
+		}
+
+		inline := false
+		fields := strings.Split(tag, ",")
+		if len(fields) > 1 {
+			for _, flag := range fields[1:] {
+				switch flag {
+				case "omitempty":
+					info.OmitEmpty = true
+				case "minsize":
+					info.MinSize = true
+				case "inline":
+					inline = true
+				default:
+					msg := fmt.Sprintf("Unsupported flag %q in tag %q of type %s", flag, tag, st)
+					panic(externalPanic(msg))
+				}
+			}
+			tag = fields[0]
+		}
+
+		if inline {
+			if field.Type.Kind() != reflect.Struct {
+				panic("Option ,inline needs a struct value field")
+			}
+			sinfo, err := getStructInfo(field.Type)
+			if err != nil {
+				return nil, err
+			}
+			for _, finfo := range sinfo.FieldsList {
+				if _, found := fieldsMap[finfo.Key]; found {
+					msg := "Duplicated key '" + finfo.Key + "' in struct " + st.String()
+					return nil, errors.New(msg)
+				}
+				if finfo.Inline == nil {
+					finfo.Inline = []int{i, finfo.Num}
+				} else {
+					finfo.Inline = append([]int{i}, finfo.Inline...)
+				}
+				fieldsMap[finfo.Key] = finfo
+				fieldsList = append(fieldsList, finfo)
+			}
+			continue
+		}
+
+		if tag != "" {
+			info.Key = tag
+		} else {
+			info.Key = strings.ToLower(field.Name)
+		}
+
+		if _, found = fieldsMap[info.Key]; found {
+			msg := "Duplicated key '" + info.Key + "' in struct " + st.String()
+			return nil, errors.New(msg)
+		}
+
+		fieldsList = append(fieldsList, info)
+		fieldsMap[info.Key] = info
+	}
+	sinfo = &structInfo{
+		fieldsMap,
+		fieldsList[:len(fieldsMap)],
+		reflect.New(st).Elem(),
+	}
+	structMapMutex.Lock()
+	structMap[st] = sinfo
+	structMapMutex.Unlock()
+	return sinfo, nil
+}

=== added file 'bson/bson_test.go'
--- bson/bson_test.go	1970-01-01 00:00:00 +0000
+++ bson/bson_test.go	2013-04-03 09:16:27 +0000
@@ -0,0 +1,1369 @@
+// BSON library for Go
+// 
+// Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+// 
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met: 
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this
+//    list of conditions and the following disclaimer. 
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution. 
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+// gobson - BSON library for Go.
+
+package bson_test
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"errors"
+	. "launchpad.net/gocheck"
+	"labix.org/v2/mgo/bson"
+	"net/url"
+	"reflect"
+	"testing"
+	"time"
+)
+
+func TestAll(t *testing.T) {
+	TestingT(t)
+}
+
+type S struct{}
+
+var _ = Suite(&S{})
+
+// Wrap up the document elements contained in data, prepending the int32
+// length of the data, and appending the '\x00' value closing the document.
+func wrapInDoc(data string) string {
+	result := make([]byte, len(data)+5)
+	binary.LittleEndian.PutUint32(result, uint32(len(result)))
+	copy(result[4:], []byte(data))
+	return string(result)
+}
+
+func makeZeroDoc(value interface{}) (zero interface{}) {
+	v := reflect.ValueOf(value)
+	t := v.Type()
+	switch t.Kind() {
+	case reflect.Map:
+		mv := reflect.MakeMap(t)
+		zero = mv.Interface()
+	case reflect.Ptr:
+		pv := reflect.New(v.Type().Elem())
+		zero = pv.Interface()
+	case reflect.Slice:
+		zero = reflect.New(t).Interface()
+	default:
+		panic("unsupported doc type")
+	}
+	return zero
+}
+
+func testUnmarshal(c *C, data string, obj interface{}) {
+	zero := makeZeroDoc(obj)
+	err := bson.Unmarshal([]byte(data), zero)
+	c.Assert(err, IsNil)
+	c.Assert(zero, DeepEquals, obj)
+}
+
+type testItemType struct {
+	obj  interface{}
+	data string
+}
+
+// --------------------------------------------------------------------------
+// Samples from bsonspec.org:
+
+var sampleItems = []testItemType{
+	{bson.M{"hello": "world"},
+		"\x16\x00\x00\x00\x02hello\x00\x06\x00\x00\x00world\x00\x00"},
+	{bson.M{"BSON": []interface{}{"awesome", float64(5.05), 1986}},
+		"1\x00\x00\x00\x04BSON\x00&\x00\x00\x00\x020\x00\x08\x00\x00\x00" +
+			"awesome\x00\x011\x00333333\x14@\x102\x00\xc2\x07\x00\x00\x00\x00"},
+}
+
+func (s *S) TestMarshalSampleItems(c *C) {
+	for i, item := range sampleItems {
+		data, err := bson.Marshal(item.obj)
+		c.Assert(err, IsNil)
+		c.Assert(string(data), Equals, item.data, Commentf("Failed on item %d", i))
+	}
+}
+
+func (s *S) TestUnmarshalSampleItems(c *C) {
+	for i, item := range sampleItems {
+		value := bson.M{}
+		err := bson.Unmarshal([]byte(item.data), value)
+		c.Assert(err, IsNil)
+		c.Assert(value, DeepEquals, item.obj, Commentf("Failed on item %d", i))
+	}
+}
+
+// --------------------------------------------------------------------------
+// Every type, ordered by the type flag. These are not wrapped with the
+// length and last \x00 from the document. wrapInDoc() computes them.
+// Note that all of them should be supported as two-way conversions.
+
+var allItems = []testItemType{
+	{bson.M{},
+		""},
+	{bson.M{"_": float64(5.05)},
+		"\x01_\x00333333\x14@"},
+	{bson.M{"_": "yo"},
+		"\x02_\x00\x03\x00\x00\x00yo\x00"},
+	{bson.M{"_": bson.M{"a": true}},
+		"\x03_\x00\x09\x00\x00\x00\x08a\x00\x01\x00"},
+	{bson.M{"_": []interface{}{true, false}},
+		"\x04_\x00\r\x00\x00\x00\x080\x00\x01\x081\x00\x00\x00"},
+	{bson.M{"_": []byte("yo")},
+		"\x05_\x00\x02\x00\x00\x00\x00yo"},
+	{bson.M{"_": bson.Binary{0x80, []byte("udef")}},
+		"\x05_\x00\x04\x00\x00\x00\x80udef"},
+	{bson.M{"_": bson.Undefined}, // Obsolete, but still seen in the wild.
+		"\x06_\x00"},
+	{bson.M{"_": bson.ObjectId("0123456789ab")},
+		"\x07_\x000123456789ab"},
+	{bson.M{"_": false},
+		"\x08_\x00\x00"},
+	{bson.M{"_": true},
+		"\x08_\x00\x01"},
+	{bson.M{"_": time.Unix(0, 258e6)}, // Note the NS <=> MS conversion.
+		"\x09_\x00\x02\x01\x00\x00\x00\x00\x00\x00"},
+	{bson.M{"_": nil},
+		"\x0A_\x00"},
+	{bson.M{"_": bson.RegEx{"ab", "cd"}},
+		"\x0B_\x00ab\x00cd\x00"},
+	{bson.M{"_": bson.JavaScript{"code", nil}},
+		"\x0D_\x00\x05\x00\x00\x00code\x00"},
+	{bson.M{"_": bson.Symbol("sym")},
+		"\x0E_\x00\x04\x00\x00\x00sym\x00"},
+	{bson.M{"_": bson.JavaScript{"code", bson.M{"": nil}}},
+		"\x0F_\x00\x14\x00\x00\x00\x05\x00\x00\x00code\x00" +
+			"\x07\x00\x00\x00\x0A\x00\x00"},
+	{bson.M{"_": 258},
+		"\x10_\x00\x02\x01\x00\x00"},
+	{bson.M{"_": bson.MongoTimestamp(258)},
+		"\x11_\x00\x02\x01\x00\x00\x00\x00\x00\x00"},
+	{bson.M{"_": int64(258)},
+		"\x12_\x00\x02\x01\x00\x00\x00\x00\x00\x00"},
+	{bson.M{"_": int64(258 << 32)},
+		"\x12_\x00\x00\x00\x00\x00\x02\x01\x00\x00"},
+	{bson.M{"_": bson.MaxKey},
+		"\x7F_\x00"},
+	{bson.M{"_": bson.MinKey},
+		"\xFF_\x00"},
+}
+
+func (s *S) TestMarshalAllItems(c *C) {
+	for i, item := range allItems {
+		data, err := bson.Marshal(item.obj)
+		c.Assert(err, IsNil)
+		c.Assert(string(data), Equals, wrapInDoc(item.data), Commentf("Failed on item %d: %#v", i, item))
+	}
+}
+
+func (s *S) TestUnmarshalAllItems(c *C) {
+	for i, item := range allItems {
+		value := bson.M{}
+		err := bson.Unmarshal([]byte(wrapInDoc(item.data)), value)
+		c.Assert(err, IsNil)
+		c.Assert(value, DeepEquals, item.obj, Commentf("Failed on item %d: %#v", i, item))
+	}
+}
+
+func (s *S) TestUnmarshalRawAllItems(c *C) {
+	for i, item := range allItems {
+		if len(item.data) == 0 {
+			continue
+		}
+		value := item.obj.(bson.M)["_"]
+		if value == nil {
+			continue
+		}
+		pv := reflect.New(reflect.ValueOf(value).Type())
+		raw := bson.Raw{item.data[0], []byte(item.data[3:])}
+		c.Logf("Unmarshal raw: %#v, %#v", raw, pv.Interface())
+		err := raw.Unmarshal(pv.Interface())
+		c.Assert(err, IsNil)
+		c.Assert(pv.Elem().Interface(), DeepEquals, value, Commentf("Failed on item %d: %#v", i, item))
+	}
+}
+
+func (s *S) TestUnmarshalRawIncompatible(c *C) {
+	raw := bson.Raw{0x08, []byte{0x01}} // true
+	err := raw.Unmarshal(&struct{}{})
+	c.Assert(err, ErrorMatches, "BSON kind 0x08 isn't compatible with type struct \\{\\}")
+}
+
+func (s *S) TestUnmarshalZeroesStruct(c *C) {
+	data, err := bson.Marshal(bson.M{"b": 2})
+	c.Assert(err, IsNil)
+	type T struct{ A, B int }
+	v := T{A: 1}
+	err = bson.Unmarshal(data, &v)
+	c.Assert(err, IsNil)
+	c.Assert(v.A, Equals, 0)
+	c.Assert(v.B, Equals, 2)
+}
+
+func (s *S) TestUnmarshalZeroesMap(c *C) {
+	data, err := bson.Marshal(bson.M{"b": 2})
+	c.Assert(err, IsNil)
+	m := bson.M{"a": 1}
+	err = bson.Unmarshal(data, &m)
+	c.Assert(err, IsNil)
+	c.Assert(m, DeepEquals, bson.M{"b": 2})
+}
+
+func (s *S) TestUnmarshalNonNilInterface(c *C) {
+	data, err := bson.Marshal(bson.M{"b": 2})
+	c.Assert(err, IsNil)
+	m := bson.M{"a": 1}
+	var i interface{}
+	i = m
+	err = bson.Unmarshal(data, &i)
+	c.Assert(err, IsNil)
+	c.Assert(i, DeepEquals, bson.M{"b": 2})
+	c.Assert(m, DeepEquals, bson.M{"a": 1})
+}
+
+// --------------------------------------------------------------------------
+// Some one way marshaling operations which would unmarshal differently.
+
+var oneWayMarshalItems = []testItemType{
+	// These are being passed as pointers, and will unmarshal as values.
+	{bson.M{"": &bson.Binary{0x02, []byte("old")}},
+		"\x05\x00\x07\x00\x00\x00\x02\x03\x00\x00\x00old"},
+	{bson.M{"": &bson.Binary{0x80, []byte("udef")}},
+		"\x05\x00\x04\x00\x00\x00\x80udef"},
+	{bson.M{"": &bson.RegEx{"ab", "cd"}},
+		"\x0B\x00ab\x00cd\x00"},
+	{bson.M{"": &bson.JavaScript{"code", nil}},
+		"\x0D\x00\x05\x00\x00\x00code\x00"},
+	{bson.M{"": &bson.JavaScript{"code", bson.M{"": nil}}},
+		"\x0F\x00\x14\x00\x00\x00\x05\x00\x00\x00code\x00" +
+			"\x07\x00\x00\x00\x0A\x00\x00"},
+
+	// There's no float32 type in BSON.  Will encode as a float64.
+	{bson.M{"": float32(5.05)},
+		"\x01\x00\x00\x00\x00@33\x14@"},
+
+	// The array will be unmarshaled as a slice instead.
+	{bson.M{"": [2]bool{true, false}},
+		"\x04\x00\r\x00\x00\x00\x080\x00\x01\x081\x00\x00\x00"},
+
+	// The typed slice will be unmarshaled as []interface{}.
+	{bson.M{"": []bool{true, false}},
+		"\x04\x00\r\x00\x00\x00\x080\x00\x01\x081\x00\x00\x00"},
+
+	// Will unmarshal as a []byte.
+	{bson.M{"": bson.Binary{0x00, []byte("yo")}},
+		"\x05\x00\x02\x00\x00\x00\x00yo"},
+	{bson.M{"": bson.Binary{0x02, []byte("old")}},
+		"\x05\x00\x07\x00\x00\x00\x02\x03\x00\x00\x00old"},
+
+	// No way to preserve the type information here. We might encode as a zero
+	// value, but this would mean that pointer values in structs wouldn't be
+	// able to correctly distinguish between unset and set to the zero value.
+	{bson.M{"": (*byte)(nil)},
+		"\x0A\x00"},
+
+	// No int types smaller than int32 in BSON. Could encode this as a char,
+	// but it would still be ambiguous, take more, and be awkward in Go when
+	// loaded without typing information.
+	{bson.M{"": byte(8)},
+		"\x10\x00\x08\x00\x00\x00"},
+
+	// There are no unsigned types in BSON.  Will unmarshal as int32 or int64.
+	{bson.M{"": uint32(258)},
+		"\x10\x00\x02\x01\x00\x00"},
+	{bson.M{"": uint64(258)},
+		"\x12\x00\x02\x01\x00\x00\x00\x00\x00\x00"},
+	{bson.M{"": uint64(258 << 32)},
+		"\x12\x00\x00\x00\x00\x00\x02\x01\x00\x00"},
+
+	// This will unmarshal as int.
+	{bson.M{"": int32(258)},
+		"\x10\x00\x02\x01\x00\x00"},
+
+	// That's a special case. The unsigned value is too large for an int32,
+	// so an int64 is used instead.
+	{bson.M{"": uint32(1<<32 - 1)},
+		"\x12\x00\xFF\xFF\xFF\xFF\x00\x00\x00\x00"},
+	{bson.M{"": uint(1<<32 - 1)},
+		"\x12\x00\xFF\xFF\xFF\xFF\x00\x00\x00\x00"},
+}
+
+func (s *S) TestOneWayMarshalItems(c *C) {
+	for i, item := range oneWayMarshalItems {
+		data, err := bson.Marshal(item.obj)
+		c.Assert(err, IsNil)
+		c.Assert(string(data), Equals, wrapInDoc(item.data),
+			Commentf("Failed on item %d", i))
+	}
+}
+
+// --------------------------------------------------------------------------
+// Two-way tests for user-defined structures using the samples
+// from bsonspec.org.
+
+type specSample1 struct {
+	Hello string
+}
+
+type specSample2 struct {
+	BSON []interface{} "BSON"
+}
+
+var structSampleItems = []testItemType{
+	{&specSample1{"world"},
+		"\x16\x00\x00\x00\x02hello\x00\x06\x00\x00\x00world\x00\x00"},
+	{&specSample2{[]interface{}{"awesome", float64(5.05), 1986}},
+		"1\x00\x00\x00\x04BSON\x00&\x00\x00\x00\x020\x00\x08\x00\x00\x00" +
+			"awesome\x00\x011\x00333333\x14@\x102\x00\xc2\x07\x00\x00\x00\x00"},
+}
+
+func (s *S) TestMarshalStructSampleItems(c *C) {
+	for i, item := range structSampleItems {
+		data, err := bson.Marshal(item.obj)
+		c.Assert(err, IsNil)
+		c.Assert(string(data), Equals, item.data,
+			Commentf("Failed on item %d", i))
+	}
+}
+
+func (s *S) TestUnmarshalStructSampleItems(c *C) {
+	for _, item := range structSampleItems {
+		testUnmarshal(c, item.data, item.obj)
+	}
+}
+
+// --------------------------------------------------------------------------
+// Generic two-way struct marshaling tests.
+
+var bytevar = byte(8)
+var byteptr = &bytevar
+
+var structItems = []testItemType{
+	{&struct{ Ptr *byte }{nil},
+		"\x0Aptr\x00"},
+	{&struct{ Ptr *byte }{&bytevar},
+		"\x10ptr\x00\x08\x00\x00\x00"},
+	{&struct{ Ptr **byte }{&byteptr},
+		"\x10ptr\x00\x08\x00\x00\x00"},
+	{&struct{ Byte byte }{8},
+		"\x10byte\x00\x08\x00\x00\x00"},
+	{&struct{ Byte byte }{0},
+		"\x10byte\x00\x00\x00\x00\x00"},
+	{&struct {
+		V byte "Tag"
+	}{8},
+		"\x10Tag\x00\x08\x00\x00\x00"},
+	{&struct {
+		V *struct {
+			Byte byte
+		}
+	}{&struct{ Byte byte }{8}},
+		"\x03v\x00" + "\x0f\x00\x00\x00\x10byte\x00\b\x00\x00\x00\x00"},
+	{&struct{ priv byte }{}, ""},
+
+	// The order of the dumped fields should be the same in the struct.
+	{&struct{ A, C, B, D, F, E *byte }{},
+		"\x0Aa\x00\x0Ac\x00\x0Ab\x00\x0Ad\x00\x0Af\x00\x0Ae\x00"},
+
+	{&struct{ V bson.Raw }{bson.Raw{0x03, []byte("\x0f\x00\x00\x00\x10byte\x00\b\x00\x00\x00\x00")}},
+		"\x03v\x00" + "\x0f\x00\x00\x00\x10byte\x00\b\x00\x00\x00\x00"},
+	{&struct{ V bson.Raw }{bson.Raw{0x10, []byte("\x00\x00\x00\x00")}},
+		"\x10v\x00" + "\x00\x00\x00\x00"},
+
+	// Byte arrays.
+	{&struct{ V [2]byte }{[2]byte{'y', 'o'}},
+		"\x05v\x00\x02\x00\x00\x00\x00yo"},
+}
+
+func (s *S) TestMarshalStructItems(c *C) {
+	for i, item := range structItems {
+		data, err := bson.Marshal(item.obj)
+		c.Assert(err, IsNil)
+		c.Assert(string(data), Equals, wrapInDoc(item.data),
+			Commentf("Failed on item %d", i))
+	}
+}
+
+func (s *S) TestUnmarshalStructItems(c *C) {
+	for _, item := range structItems {
+		testUnmarshal(c, wrapInDoc(item.data), item.obj)
+	}
+}
+
+func (s *S) TestUnmarshalRawStructItems(c *C) {
+	for i, item := range structItems {
+		raw := bson.Raw{0x03, []byte(wrapInDoc(item.data))}
+		zero := makeZeroDoc(item.obj)
+		err := raw.Unmarshal(zero)
+		c.Assert(err, IsNil)
+		c.Assert(zero, DeepEquals, item.obj, Commentf("Failed on item %d: %#v", i, item))
+	}
+}
+
+func (s *S) TestUnmarshalRawNil(c *C) {
+	// Regression test: shouldn't try to nil out the pointer itself,
+	// as it's not settable.
+	raw := bson.Raw{0x0A, []byte{}}
+	err := raw.Unmarshal(&struct{}{})
+	c.Assert(err, IsNil)
+}
+
+// --------------------------------------------------------------------------
+// One-way marshaling tests.
+
+type dOnIface struct {
+	D interface{}
+}
+
+type ignoreField struct {
+	Before string
+	Ignore string `bson:"-"`
+	After  string
+}
+
+var marshalItems = []testItemType{
+	// Ordered document dump.  Will unmarshal as a dictionary by default.
+	{bson.D{{"a", nil}, {"c", nil}, {"b", nil}, {"d", nil}, {"f", nil}, {"e", true}},
+		"\x0Aa\x00\x0Ac\x00\x0Ab\x00\x0Ad\x00\x0Af\x00\x08e\x00\x01"},
+	{MyD{{"a", nil}, {"c", nil}, {"b", nil}, {"d", nil}, {"f", nil}, {"e", true}},
+		"\x0Aa\x00\x0Ac\x00\x0Ab\x00\x0Ad\x00\x0Af\x00\x08e\x00\x01"},
+	{&dOnIface{bson.D{{"a", nil}, {"c", nil}, {"b", nil}, {"d", true}}},
+		"\x03d\x00" + wrapInDoc("\x0Aa\x00\x0Ac\x00\x0Ab\x00\x08d\x00\x01")},
+	{&ignoreField{"before", "ignore", "after"},
+		"\x02before\x00\a\x00\x00\x00before\x00\x02after\x00\x06\x00\x00\x00after\x00"},
+
+	// Marshalling a Raw document does nothing.
+	{bson.Raw{0x03, []byte(wrapInDoc("anything"))},
+		"anything"},
+	{bson.Raw{Data: []byte(wrapInDoc("anything"))},
+		"anything"},
+}
+
+func (s *S) TestMarshalOneWayItems(c *C) {
+	for _, item := range marshalItems {
+		data, err := bson.Marshal(item.obj)
+		c.Assert(err, IsNil)
+		c.Assert(string(data), Equals, wrapInDoc(item.data))
+	}
+}
+
+// --------------------------------------------------------------------------
+// One-way unmarshaling tests.
+
+var unmarshalItems = []testItemType{
+	// Field is private.  Should not attempt to unmarshal it.
+	{&struct{ priv byte }{},
+		"\x10priv\x00\x08\x00\x00\x00"},
+
+	// Wrong casing. Field names are lowercased.
+	{&struct{ Byte byte }{},
+		"\x10Byte\x00\x08\x00\x00\x00"},
+
+	// Ignore non-existing field.
+	{&struct{ Byte byte }{9},
+		"\x10boot\x00\x08\x00\x00\x00" + "\x10byte\x00\x09\x00\x00\x00"},
+
+	// Do not unmarshal on ignored field.
+	{&ignoreField{"before", "", "after"},
+		"\x02before\x00\a\x00\x00\x00before\x00" +
+			"\x02-\x00\a\x00\x00\x00ignore\x00" +
+			"\x02after\x00\x06\x00\x00\x00after\x00"},
+
+	// Ignore unsuitable types silently.
+	{map[string]string{"str": "s"},
+		"\x02str\x00\x02\x00\x00\x00s\x00" + "\x10int\x00\x01\x00\x00\x00"},
+	{map[string][]int{"array": []int{5, 9}},
+		"\x04array\x00" + wrapInDoc("\x100\x00\x05\x00\x00\x00"+"\x021\x00\x02\x00\x00\x00s\x00"+"\x102\x00\x09\x00\x00\x00")},
+
+	// Wrong type. Shouldn't init pointer.
+	{&struct{ Str *byte }{},
+		"\x02str\x00\x02\x00\x00\x00s\x00"},
+	{&struct{ Str *struct{ Str string } }{},
+		"\x02str\x00\x02\x00\x00\x00s\x00"},
+
+	// Ordered document.
+	{&struct{ bson.D }{bson.D{{"a", nil}, {"c", nil}, {"b", nil}, {"d", true}}},
+		"\x03d\x00" + wrapInDoc("\x0Aa\x00\x0Ac\x00\x0Ab\x00\x08d\x00\x01")},
+
+	// Raw document.
+	{&bson.Raw{0x03, []byte(wrapInDoc("\x10byte\x00\x08\x00\x00\x00"))},
+		"\x10byte\x00\x08\x00\x00\x00"},
+
+	// Decode old binary.
+	{bson.M{"_": []byte("old")},
+		"\x05_\x00\x07\x00\x00\x00\x02\x03\x00\x00\x00old"},
+}
+
+func (s *S) TestUnmarshalOneWayItems(c *C) {
+	for _, item := range unmarshalItems {
+		testUnmarshal(c, wrapInDoc(item.data), item.obj)
+	}
+}
+
+func (s *S) TestUnmarshalNilInStruct(c *C) {
+	// Nil is the default value, so we need to ensure it's indeed being set.
+	b := byte(1)
+	v := &struct{ Ptr *byte }{&b}
+	err := bson.Unmarshal([]byte(wrapInDoc("\x0Aptr\x00")), v)
+	c.Assert(err, IsNil)
+	c.Assert(v, DeepEquals, &struct{ Ptr *byte }{nil})
+}
+
+// --------------------------------------------------------------------------
+// Marshalling error cases.
+
+type structWithDupKeys struct {
+	Name  byte
+	Other byte "name" // Tag should precede.
+}
+
+var marshalErrorItems = []testItemType{
+	{bson.M{"": uint64(1 << 63)},
+		"BSON has no uint64 type, and value is too large to fit correctly in an int64"},
+	{bson.M{"": bson.ObjectId("tooshort")},
+		"ObjectIDs must be exactly 12 bytes long \\(got 8\\)"},
+	{int64(123),
+		"Can't marshal int64 as a BSON document"},
+	{bson.M{"": 1i},
+		"Can't marshal complex128 in a BSON document"},
+	{&structWithDupKeys{},
+		"Duplicated key 'name' in struct bson_test.structWithDupKeys"},
+	{bson.Raw{0x0A, []byte{}},
+		"Attempted to unmarshal Raw kind 10 as a document"},
+	{&inlineCantPtr{&struct{ A, B int }{1, 2}},
+		"Option ,inline needs a struct value field"},
+	{&inlineDupName{1, struct{ A, B int }{2, 3}},
+		"Duplicated key 'a' in struct bson_test.inlineDupName"},
+}
+
+func (s *S) TestMarshalErrorItems(c *C) {
+	for _, item := range marshalErrorItems {
+		data, err := bson.Marshal(item.obj)
+		c.Assert(err, ErrorMatches, item.data)
+		c.Assert(data, IsNil)
+	}
+}
+
+// --------------------------------------------------------------------------
+// Unmarshalling error cases.
+
+type unmarshalErrorType struct {
+	obj   interface{}
+	data  string
+	error string
+}
+
+var unmarshalErrorItems = []unmarshalErrorType{
+	// Tag name conflicts with existing parameter.
+	{&structWithDupKeys{},
+		"\x10name\x00\x08\x00\x00\x00",
+		"Duplicated key 'name' in struct bson_test.structWithDupKeys"},
+
+	// Non-string map key.
+	{map[int]interface{}{},
+		"\x10name\x00\x08\x00\x00\x00",
+		"BSON map must have string keys. Got: map\\[int\\]interface \\{\\}"},
+
+	{nil,
+		"\xEEname\x00",
+		"Unknown element kind \\(0xEE\\)"},
+
+	{struct{ Name bool }{},
+		"\x10name\x00\x08\x00\x00\x00",
+		"Unmarshal can't deal with struct values. Use a pointer."},
+
+	{123,
+		"\x10name\x00\x08\x00\x00\x00",
+		"Unmarshal needs a map or a pointer to a struct."},
+}
+
+func (s *S) TestUnmarshalErrorItems(c *C) {
+	for _, item := range unmarshalErrorItems {
+		data := []byte(wrapInDoc(item.data))
+		var value interface{}
+		switch reflect.ValueOf(item.obj).Kind() {
+		case reflect.Map, reflect.Ptr:
+			value = makeZeroDoc(item.obj)
+		case reflect.Invalid:
+			value = bson.M{}
+		default:
+			value = item.obj
+		}
+		err := bson.Unmarshal(data, value)
+		c.Assert(err, ErrorMatches, item.error)
+	}
+}
+
+type unmarshalRawErrorType struct {
+	obj   interface{}
+	raw   bson.Raw
+	error string
+}
+
+var unmarshalRawErrorItems = []unmarshalRawErrorType{
+	// Tag name conflicts with existing parameter.
+	{&structWithDupKeys{},
+		bson.Raw{0x03, []byte("\x10byte\x00\x08\x00\x00\x00")},
+		"Duplicated key 'name' in struct bson_test.structWithDupKeys"},
+
+	{&struct{}{},
+		bson.Raw{0xEE, []byte{}},
+		"Unknown element kind \\(0xEE\\)"},
+
+	{struct{ Name bool }{},
+		bson.Raw{0x10, []byte("\x08\x00\x00\x00")},
+		"Raw Unmarshal can't deal with struct values. Use a pointer."},
+
+	{123,
+		bson.Raw{0x10, []byte("\x08\x00\x00\x00")},
+		"Raw Unmarshal needs a map or a valid pointer."},
+}
+
+func (s *S) TestUnmarshalRawErrorItems(c *C) {
+	for i, item := range unmarshalRawErrorItems {
+		err := item.raw.Unmarshal(item.obj)
+		c.Assert(err, ErrorMatches, item.error, Commentf("Failed on item %d: %#v\n", i, item))
+	}
+}
+
+var corruptedData = []string{
+	"\x04\x00\x00\x00\x00",         // Shorter than minimum
+	"\x06\x00\x00\x00\x00",         // Not enough data
+	"\x05\x00\x00",                 // Broken length
+	"\x05\x00\x00\x00\xff",         // Corrupted termination
+	"\x0A\x00\x00\x00\x0Aooop\x00", // Unfinished C string
+
+	// Array end past end of string (s[2]=0x07 is correct)
+	wrapInDoc("\x04\x00\x09\x00\x00\x00\x0A\x00\x00"),
+
+	// Array end within string, but past acceptable.
+	wrapInDoc("\x04\x00\x08\x00\x00\x00\x0A\x00\x00"),
+
+	// Document end within string, but past acceptable.
+	wrapInDoc("\x03\x00\x08\x00\x00\x00\x0A\x00\x00"),
+
+	// String with corrupted end.
+	wrapInDoc("\x02\x00\x03\x00\x00\x00yo\xFF"),
+}
+
+func (s *S) TestUnmarshalMapDocumentTooShort(c *C) {
+	for _, data := range corruptedData {
+		err := bson.Unmarshal([]byte(data), bson.M{})
+		c.Assert(err, ErrorMatches, "Document is corrupted")
+
+		err = bson.Unmarshal([]byte(data), &struct{}{})
+		c.Assert(err, ErrorMatches, "Document is corrupted")
+	}
+}
+
+// --------------------------------------------------------------------------
+// Setter test cases.
+
+var setterResult = map[string]error{}
+
+type setterType struct {
+	received interface{}
+}
+
+func (o *setterType) SetBSON(raw bson.Raw) error {
+	err := raw.Unmarshal(&o.received)
+	if err != nil {
+		panic("The panic:" + err.Error())
+	}
+	if s, ok := o.received.(string); ok {
+		if result, ok := setterResult[s]; ok {
+			return result
+		}
+	}
+	return nil
+}
+
+type ptrSetterDoc struct {
+	Field *setterType "_"
+}
+
+type valSetterDoc struct {
+	Field setterType "_"
+}
+
+func (s *S) TestUnmarshalAllItemsWithPtrSetter(c *C) {
+	for _, item := range allItems {
+		for i := 0; i != 2; i++ {
+			var field *setterType
+			if i == 0 {
+				obj := &ptrSetterDoc{}
+				err := bson.Unmarshal([]byte(wrapInDoc(item.data)), obj)
+				c.Assert(err, IsNil)
+				field = obj.Field
+			} else {
+				obj := &valSetterDoc{}
+				err := bson.Unmarshal([]byte(wrapInDoc(item.data)), obj)
+				c.Assert(err, IsNil)
+				field = &obj.Field
+			}
+			if item.data == "" {
+				// Nothing to unmarshal. Should be untouched.
+				if i == 0 {
+					c.Assert(field, IsNil)
+				} else {
+					c.Assert(field.received, IsNil)
+				}
+			} else {
+				expected := item.obj.(bson.M)["_"]
+				c.Assert(field, NotNil, Commentf("Pointer not initialized (%#v)", expected))
+				c.Assert(field.received, DeepEquals, expected)
+			}
+		}
+	}
+}
+
+func (s *S) TestUnmarshalWholeDocumentWithSetter(c *C) {
+	obj := &setterType{}
+	err := bson.Unmarshal([]byte(sampleItems[0].data), obj)
+	c.Assert(err, IsNil)
+	c.Assert(obj.received, DeepEquals, bson.M{"hello": "world"})
+}
+
+func (s *S) TestUnmarshalSetterOmits(c *C) {
+	setterResult["2"] = &bson.TypeError{}
+	setterResult["4"] = &bson.TypeError{}
+	defer func() {
+		delete(setterResult, "2")
+		delete(setterResult, "4")
+	}()
+
+	m := map[string]*setterType{}
+	data := wrapInDoc("\x02abc\x00\x02\x00\x00\x001\x00" +
+		"\x02def\x00\x02\x00\x00\x002\x00" +
+		"\x02ghi\x00\x02\x00\x00\x003\x00" +
+		"\x02jkl\x00\x02\x00\x00\x004\x00")
+	err := bson.Unmarshal([]byte(data), m)
+	c.Assert(err, IsNil)
+	c.Assert(m["abc"], NotNil)
+	c.Assert(m["def"], IsNil)
+	c.Assert(m["ghi"], NotNil)
+	c.Assert(m["jkl"], IsNil)
+
+	c.Assert(m["abc"].received, Equals, "1")
+	c.Assert(m["ghi"].received, Equals, "3")
+}
+
+func (s *S) TestUnmarshalSetterErrors(c *C) {
+	boom := errors.New("BOOM")
+	setterResult["2"] = boom
+	defer delete(setterResult, "2")
+
+	m := map[string]*setterType{}
+	data := wrapInDoc("\x02abc\x00\x02\x00\x00\x001\x00" +
+		"\x02def\x00\x02\x00\x00\x002\x00" +
+		"\x02ghi\x00\x02\x00\x00\x003\x00")
+	err := bson.Unmarshal([]byte(data), m)
+	c.Assert(err, Equals, boom)
+	c.Assert(m["abc"], NotNil)
+	c.Assert(m["def"], IsNil)
+	c.Assert(m["ghi"], IsNil)
+
+	c.Assert(m["abc"].received, Equals, "1")
+}
+
+func (s *S) TestDMap(c *C) {
+	d := bson.D{{"a", 1}, {"b", 2}}
+	c.Assert(d.Map(), DeepEquals, bson.M{"a": 1, "b": 2})
+}
+
+func (s *S) TestUnmarshalSetterSetZero(c *C) {
+	setterResult["foo"] = bson.SetZero
+	defer delete(setterResult, "field")
+
+	data, err := bson.Marshal(bson.M{"field": "foo"})
+	c.Assert(err, IsNil)
+
+	m := map[string]*setterType{}
+	err = bson.Unmarshal([]byte(data), m)
+	c.Assert(err, IsNil)
+
+	value, ok := m["field"]
+	c.Assert(ok, Equals, true)
+	c.Assert(value, IsNil)
+}
+
+
+// --------------------------------------------------------------------------
+// Getter test cases.
+
+type typeWithGetter struct {
+	result interface{}
+	err    error
+}
+
+func (t *typeWithGetter) GetBSON() (interface{}, error) {
+	return t.result, t.err
+}
+
+type docWithGetterField struct {
+	Field *typeWithGetter "_"
+}
+
+func (s *S) TestMarshalAllItemsWithGetter(c *C) {
+	for i, item := range allItems {
+		if item.data == "" {
+			continue
+		}
+		obj := &docWithGetterField{}
+		obj.Field = &typeWithGetter{result: item.obj.(bson.M)["_"]}
+		data, err := bson.Marshal(obj)
+		c.Assert(err, IsNil)
+		c.Assert(string(data), Equals, wrapInDoc(item.data),
+			Commentf("Failed on item #%d", i))
+	}
+}
+
+func (s *S) TestMarshalWholeDocumentWithGetter(c *C) {
+	obj := &typeWithGetter{result: sampleItems[0].obj}
+	data, err := bson.Marshal(obj)
+	c.Assert(err, IsNil)
+	c.Assert(string(data), Equals, sampleItems[0].data)
+}
+
+func (s *S) TestGetterErrors(c *C) {
+	e := errors.New("oops")
+
+	obj1 := &docWithGetterField{}
+	obj1.Field = &typeWithGetter{sampleItems[0].obj, e}
+	data, err := bson.Marshal(obj1)
+	c.Assert(err, ErrorMatches, "oops")
+	c.Assert(data, IsNil)
+
+	obj2 := &typeWithGetter{sampleItems[0].obj, e}
+	data, err = bson.Marshal(obj2)
+	c.Assert(err, ErrorMatches, "oops")
+	c.Assert(data, IsNil)
+}
+
+type intGetter int64
+
+func (t intGetter) GetBSON() (interface{}, error) {
+	return int64(t), nil
+}
+
+type typeWithIntGetter struct {
+	V intGetter ",minsize"
+}
+
+func (s *S) TestMarshalShortWithGetter(c *C) {
+	obj := typeWithIntGetter{42}
+	data, err := bson.Marshal(obj)
+	c.Assert(err, IsNil)
+	m := bson.M{}
+	err = bson.Unmarshal(data, m)
+	c.Assert(m["v"], Equals, 42)
+}
+
+// --------------------------------------------------------------------------
+// Cross-type conversion tests.
+
+type crossTypeItem struct {
+	obj1 interface{}
+	obj2 interface{}
+}
+
+type condStr struct {
+	V string ",omitempty"
+}
+type condStrNS struct {
+	V string `a:"A" bson:",omitempty" b:"B"`
+}
+type condBool struct {
+	V bool ",omitempty"
+}
+type condInt struct {
+	V int ",omitempty"
+}
+type condUInt struct {
+	V uint ",omitempty"
+}
+type condFloat struct {
+	V float64 ",omitempty"
+}
+type condIface struct {
+	V interface{} ",omitempty"
+}
+type condPtr struct {
+	V *bool ",omitempty"
+}
+type condSlice struct {
+	V []string ",omitempty"
+}
+type condMap struct {
+	V map[string]int ",omitempty"
+}
+type namedCondStr struct {
+	V string "myv,omitempty"
+}
+type condTime struct {
+	V time.Time ",omitempty"
+}
+
+type shortInt struct {
+	V int64 ",minsize"
+}
+type shortUint struct {
+	V uint64 ",minsize"
+}
+type shortIface struct {
+	V interface{} ",minsize"
+}
+type shortPtr struct {
+	V *int64 ",minsize"
+}
+type shortNonEmptyInt struct {
+	V int64 ",minsize,omitempty"
+}
+
+type inlineInt struct {
+	V struct{ A, B int } ",inline"
+}
+type inlineCantPtr struct {
+	V *struct{ A, B int } ",inline"
+}
+type inlineDupName struct {
+	A int
+	V struct{ A, B int } ",inline"
+}
+
+type MyBytes []byte
+type MyBool bool
+type MyD []bson.DocElem
+type MyM map[string]interface{}
+
+var truevar = true
+var falsevar = false
+
+var int64var = int64(42)
+var int64ptr = &int64var
+var intvar = int(42)
+var intptr = &intvar
+
+func parseURL(s string) *url.URL {
+	u, err := url.Parse(s)
+	if err != nil {
+		panic(err)
+	}
+	return u
+}
+
+// That's a pretty fun test.  It will dump the first item, generate a zero
+// value equivalent to the second one, load the dumped data onto it, and then
+// verify that the resulting value is deep-equal to the untouched second value.
+// Then, it will do the same in the *opposite* direction!
+var twoWayCrossItems = []crossTypeItem{
+	// int<=>int
+	{&struct{ I int }{42}, &struct{ I int8 }{42}},
+	{&struct{ I int }{42}, &struct{ I int32 }{42}},
+	{&struct{ I int }{42}, &struct{ I int64 }{42}},
+	{&struct{ I int8 }{42}, &struct{ I int32 }{42}},
+	{&struct{ I int8 }{42}, &struct{ I int64 }{42}},
+	{&struct{ I int32 }{42}, &struct{ I int64 }{42}},
+
+	// uint<=>uint
+	{&struct{ I uint }{42}, &struct{ I uint8 }{42}},
+	{&struct{ I uint }{42}, &struct{ I uint32 }{42}},
+	{&struct{ I uint }{42}, &struct{ I uint64 }{42}},
+	{&struct{ I uint8 }{42}, &struct{ I uint32 }{42}},
+	{&struct{ I uint8 }{42}, &struct{ I uint64 }{42}},
+	{&struct{ I uint32 }{42}, &struct{ I uint64 }{42}},
+
+	// float32<=>float64
+	{&struct{ I float32 }{42}, &struct{ I float64 }{42}},
+
+	// int<=>uint
+	{&struct{ I uint }{42}, &struct{ I int }{42}},
+	{&struct{ I uint }{42}, &struct{ I int8 }{42}},
+	{&struct{ I uint }{42}, &struct{ I int32 }{42}},
+	{&struct{ I uint }{42}, &struct{ I int64 }{42}},
+	{&struct{ I uint8 }{42}, &struct{ I int }{42}},
+	{&struct{ I uint8 }{42}, &struct{ I int8 }{42}},
+	{&struct{ I uint8 }{42}, &struct{ I int32 }{42}},
+	{&struct{ I uint8 }{42}, &struct{ I int64 }{42}},
+	{&struct{ I uint32 }{42}, &struct{ I int }{42}},
+	{&struct{ I uint32 }{42}, &struct{ I int8 }{42}},
+	{&struct{ I uint32 }{42}, &struct{ I int32 }{42}},
+	{&struct{ I uint32 }{42}, &struct{ I int64 }{42}},
+	{&struct{ I uint64 }{42}, &struct{ I int }{42}},
+	{&struct{ I uint64 }{42}, &struct{ I int8 }{42}},
+	{&struct{ I uint64 }{42}, &struct{ I int32 }{42}},
+	{&struct{ I uint64 }{42}, &struct{ I int64 }{42}},
+
+	// int <=> float
+	{&struct{ I int }{42}, &struct{ I float64 }{42}},
+
+	// int <=> bool
+	{&struct{ I int }{1}, &struct{ I bool }{true}},
+	{&struct{ I int }{0}, &struct{ I bool }{false}},
+
+	// uint <=> float64
+	{&struct{ I uint }{42}, &struct{ I float64 }{42}},
+
+	// uint <=> bool
+	{&struct{ I uint }{1}, &struct{ I bool }{true}},
+	{&struct{ I uint }{0}, &struct{ I bool }{false}},
+
+	// float64 <=> bool
+	{&struct{ I float64 }{1}, &struct{ I bool }{true}},
+	{&struct{ I float64 }{0}, &struct{ I bool }{false}},
+
+	// string <=> string and string <=> []byte
+	{&struct{ S []byte }{[]byte("abc")}, &struct{ S string }{"abc"}},
+	{&struct{ S []byte }{[]byte("def")}, &struct{ S bson.Symbol }{"def"}},
+	{&struct{ S string }{"ghi"}, &struct{ S bson.Symbol }{"ghi"}},
+
+	// map <=> struct
+	{&struct {
+		A struct {
+			B, C int
+		}
+	}{struct{ B, C int }{1, 2}},
+		map[string]map[string]int{"a": map[string]int{"b": 1, "c": 2}}},
+
+	{&struct{ A bson.Symbol }{"abc"}, map[string]string{"a": "abc"}},
+	{&struct{ A bson.Symbol }{"abc"}, map[string][]byte{"a": []byte("abc")}},
+	{&struct{ A []byte }{[]byte("abc")}, map[string]string{"a": "abc"}},
+	{&struct{ A uint }{42}, map[string]int{"a": 42}},
+	{&struct{ A uint }{42}, map[string]float64{"a": 42}},
+	{&struct{ A uint }{1}, map[string]bool{"a": true}},
+	{&struct{ A int }{42}, map[string]uint{"a": 42}},
+	{&struct{ A int }{42}, map[string]float64{"a": 42}},
+	{&struct{ A int }{1}, map[string]bool{"a": true}},
+	{&struct{ A float64 }{42}, map[string]float32{"a": 42}},
+	{&struct{ A float64 }{42}, map[string]int{"a": 42}},
+	{&struct{ A float64 }{42}, map[string]uint{"a": 42}},
+	{&struct{ A float64 }{1}, map[string]bool{"a": true}},
+	{&struct{ A bool }{true}, map[string]int{"a": 1}},
+	{&struct{ A bool }{true}, map[string]uint{"a": 1}},
+	{&struct{ A bool }{true}, map[string]float64{"a": 1}},
+	{&struct{ A **byte }{&byteptr}, map[string]byte{"a": 8}},
+
+	// url.URL <=> string
+	{&struct{ URL *url.URL }{parseURL("h://e.c/p")}, map[string]string{"url": "h://e.c/p"}},
+	{&struct{ URL url.URL }{*parseURL("h://e.c/p")}, map[string]string{"url": "h://e.c/p"}},
+
+	// Slices
+	{&struct{ S []int }{[]int{1, 2, 3}}, map[string][]int{"s": []int{1, 2, 3}}},
+	{&struct{ S *[]int }{&[]int{1, 2, 3}}, map[string][]int{"s": []int{1, 2, 3}}},
+
+	// Conditionals
+	{&condBool{true}, map[string]bool{"v": true}},
+	{&condBool{}, map[string]bool{}},
+	{&condInt{1}, map[string]int{"v": 1}},
+	{&condInt{}, map[string]int{}},
+	{&condUInt{1}, map[string]uint{"v": 1}},
+	{&condUInt{}, map[string]uint{}},
+	{&condFloat{}, map[string]int{}},
+	{&condStr{"yo"}, map[string]string{"v": "yo"}},
+	{&condStr{}, map[string]string{}},
+	{&condStrNS{"yo"}, map[string]string{"v": "yo"}},
+	{&condStrNS{}, map[string]string{}},
+	{&condSlice{[]string{"yo"}}, map[string][]string{"v": []string{"yo"}}},
+	{&condSlice{}, map[string][]string{}},
+	{&condMap{map[string]int{"k": 1}}, bson.M{"v": bson.M{"k": 1}}},
+	{&condMap{}, map[string][]string{}},
+	{&condIface{"yo"}, map[string]string{"v": "yo"}},
+	{&condIface{""}, map[string]string{"v": ""}},
+	{&condIface{}, map[string]string{}},
+	{&condPtr{&truevar}, map[string]bool{"v": true}},
+	{&condPtr{&falsevar}, map[string]bool{"v": false}},
+	{&condPtr{}, map[string]string{}},
+
+	{&condTime{time.Unix(123456789, 123e6)}, map[string]time.Time{"v": time.Unix(123456789, 123e6)}},
+	{&condTime{}, map[string]string{}},
+
+	{&namedCondStr{"yo"}, map[string]string{"myv": "yo"}},
+	{&namedCondStr{}, map[string]string{}},
+
+	{&shortInt{1}, map[string]interface{}{"v": 1}},
+	{&shortInt{1 << 30}, map[string]interface{}{"v": 1 << 30}},
+	{&shortInt{1 << 31}, map[string]interface{}{"v": int64(1 << 31)}},
+	{&shortUint{1 << 30}, map[string]interface{}{"v": 1 << 30}},
+	{&shortUint{1 << 31}, map[string]interface{}{"v": int64(1 << 31)}},
+	{&shortIface{int64(1) << 31}, map[string]interface{}{"v": int64(1 << 31)}},
+	{&shortPtr{int64ptr}, map[string]interface{}{"v": intvar}},
+
+	{&shortNonEmptyInt{1}, map[string]interface{}{"v": 1}},
+	{&shortNonEmptyInt{1 << 31}, map[string]interface{}{"v": int64(1 << 31)}},
+	{&shortNonEmptyInt{}, map[string]interface{}{}},
+
+	{&inlineInt{struct{ A, B int }{1, 2}}, map[string]interface{}{"a": 1, "b": 2}},
+
+	// []byte <=> MyBytes
+	{&struct{ B MyBytes }{[]byte("abc")}, map[string]string{"b": "abc"}},
+	{&struct{ B MyBytes }{[]byte{}}, map[string]string{"b": ""}},
+	{&struct{ B MyBytes }{}, map[string]bool{}},
+	{&struct{ B []byte }{[]byte("abc")}, map[string]MyBytes{"b": []byte("abc")}},
+
+	// bool <=> MyBool
+	{&struct{ B MyBool }{true}, map[string]bool{"b": true}},
+	{&struct{ B MyBool }{}, map[string]bool{"b": false}},
+	{&struct{ B MyBool }{}, map[string]string{}},
+	{&struct{ B bool }{}, map[string]MyBool{"b": false}},
+
+	// arrays
+	{&struct{ V [2]int }{[...]int{1, 2}}, map[string][2]int{"v": [2]int{1, 2}}},
+
+	// zero time
+	{&struct{ V time.Time }{}, map[string]interface{}{"v": time.Time{}}},
+
+	// zero time + 1 second + 1 millisecond; overflows int64 as nanoseconds
+	{&struct{ V time.Time }{time.Unix(-62135596799, 1e6).Local()},
+		map[string]interface{}{"v": time.Unix(-62135596799, 1e6).Local()}},
+
+	// bson.D <=> []DocElem
+	{&bson.D{{"a", bson.D{{"b", 1}, {"c", 2}}}}, &bson.D{{"a", bson.D{{"b", 1}, {"c", 2}}}}},
+	{&bson.D{{"a", bson.D{{"b", 1}, {"c", 2}}}}, &MyD{{"a", MyD{{"b", 1}, {"c", 2}}}}},
+
+	// bson.M <=> map
+	{bson.M{"a": bson.M{"b": 1, "c": 2}}, MyM{"a": MyM{"b": 1, "c": 2}}},
+	{bson.M{"a": bson.M{"b": 1, "c": 2}}, map[string]interface{}{"a": map[string]interface{}{"b": 1, "c": 2}}},
+}
+
+// Same thing, but only one way (obj1 => obj2).
+var oneWayCrossItems = []crossTypeItem{
+	// map <=> struct
+	{map[string]interface{}{"a": 1, "b": "2", "c": 3},
+		map[string]int{"a": 1, "c": 3}},
+
+	// Can't decode int into struct.
+	{bson.M{"a": bson.M{"b": 2}}, &struct{ A bool }{}},
+
+	// Would get decoded into a int32 too in the opposite direction.
+	{&shortIface{int64(1) << 30}, map[string]interface{}{"v": 1 << 30}},
+}
+
+func testCrossPair(c *C, dump interface{}, load interface{}) {
+	c.Logf("Dump: %#v", dump)
+	c.Logf("Load: %#v", load)
+	zero := makeZeroDoc(load)
+	data, err := bson.Marshal(dump)
+	c.Assert(err, IsNil)
+	c.Logf("Dumped: %#v", string(data))
+	err = bson.Unmarshal(data, zero)
+	c.Assert(err, IsNil)
+	c.Logf("Loaded: %#v", zero)
+	c.Assert(zero, DeepEquals, load)
+}
+
+func (s *S) TestTwoWayCrossPairs(c *C) {
+	for _, item := range twoWayCrossItems {
+		testCrossPair(c, item.obj1, item.obj2)
+		testCrossPair(c, item.obj2, item.obj1)
+	}
+}
+
+func (s *S) TestOneWayCrossPairs(c *C) {
+	for _, item := range oneWayCrossItems {
+		testCrossPair(c, item.obj1, item.obj2)
+	}
+}
+
+// --------------------------------------------------------------------------
+// ObjectId hex representation test.
+
+func (s *S) TestObjectIdHex(c *C) {
+	id := bson.ObjectIdHex("4d88e15b60f486e428412dc9")
+	c.Assert(id.String(), Equals, `ObjectIdHex("4d88e15b60f486e428412dc9")`)
+	c.Assert(id.Hex(), Equals, "4d88e15b60f486e428412dc9")
+}
+
+func (s *S) TestIsObjectIdHex(c *C) {
+	test := []struct{ id string; valid bool }{
+		{"4d88e15b60f486e428412dc9", true},
+		{"4d88e15b60f486e428412dc", false},
+		{"4d88e15b60f486e428412dc9e", false},
+		{"4d88e15b60f486e428412dcx", false},
+	}
+	for _, t := range test {
+		c.Assert(bson.IsObjectIdHex(t.id), Equals, t.valid)
+	}
+}
+
+// --------------------------------------------------------------------------
+// ObjectId parts extraction tests.
+
+type objectIdParts struct {
+	id        bson.ObjectId
+	timestamp int64
+	machine   []byte
+	pid       uint16
+	counter   int32
+}
+
+var objectIds = []objectIdParts{
+	objectIdParts{
+		bson.ObjectIdHex("4d88e15b60f486e428412dc9"),
+		1300816219,
+		[]byte{0x60, 0xf4, 0x86},
+		0xe428,
+		4271561,
+	},
+	objectIdParts{
+		bson.ObjectIdHex("000000000000000000000000"),
+		0,
+		[]byte{0x00, 0x00, 0x00},
+		0x0000,
+		0,
+	},
+	objectIdParts{
+		bson.ObjectIdHex("00000000aabbccddee000001"),
+		0,
+		[]byte{0xaa, 0xbb, 0xcc},
+		0xddee,
+		1,
+	},
+}
+
+func (s *S) TestObjectIdPartsExtraction(c *C) {
+	for i, v := range objectIds {
+		t := time.Unix(v.timestamp, 0)
+		c.Assert(v.id.Time(), Equals, t, Commentf("#%d Wrong timestamp value", i))
+		c.Assert(v.id.Machine(), DeepEquals, v.machine, Commentf("#%d Wrong machine id value", i))
+		c.Assert(v.id.Pid(), Equals, v.pid, Commentf("#%d Wrong pid value", i))
+		c.Assert(v.id.Counter(), Equals, v.counter, Commentf("#%d Wrong counter value", i))
+	}
+}
+
+func (s *S) TestNow(c *C) {
+	before := time.Now()
+	time.Sleep(1e6)
+	now := bson.Now()
+	time.Sleep(1e6)
+	after := time.Now()
+	c.Assert(now.After(before) && now.Before(after), Equals, true, Commentf("now=%s, before=%s, after=%s", now, before, after))
+}
+
+// --------------------------------------------------------------------------
+// ObjectId generation tests.
+
+func (s *S) TestNewObjectId(c *C) {
+	// Generate 10 ids
+	ids := make([]bson.ObjectId, 10)
+	for i := 0; i < 10; i++ {
+		ids[i] = bson.NewObjectId()
+	}
+	for i := 1; i < 10; i++ {
+		prevId := ids[i-1]
+		id := ids[i]
+		// Test for uniqueness among all other 9 generated ids
+		for j, tid := range ids {
+			if j != i {
+				c.Assert(id, Not(Equals), tid, Commentf("Generated ObjectId is not unique"))
+			}
+		}
+		// Check that timestamp was incremented and is within 30 seconds of the previous one
+		secs := id.Time().Sub(prevId.Time()).Seconds()
+		c.Assert((secs >= 0 && secs <= 30), Equals, true, Commentf("Wrong timestamp in generated ObjectId"))
+		// Check that machine ids are the same
+		c.Assert(id.Machine(), DeepEquals, prevId.Machine())
+		// Check that pids are the same
+		c.Assert(id.Pid(), Equals, prevId.Pid())
+		// Test for proper increment
+		delta := int(id.Counter() - prevId.Counter())
+		c.Assert(delta, Equals, 1, Commentf("Wrong increment in generated ObjectId"))
+	}
+}
+
+func (s *S) TestNewObjectIdWithTime(c *C) {
+	t := time.Unix(12345678, 0)
+	id := bson.NewObjectIdWithTime(t)
+	c.Assert(id.Time(), Equals, t)
+	c.Assert(id.Machine(), DeepEquals, []byte{0x00, 0x00, 0x00})
+	c.Assert(int(id.Pid()), Equals, 0)
+	c.Assert(int(id.Counter()), Equals, 0)
+}
+
+// --------------------------------------------------------------------------
+// ObjectId JSON marshalling.
+
+type jsonType struct {
+	Id *bson.ObjectId
+}
+
+func (s *S) TestObjectIdJSONMarshaling(c *C) {
+	id := bson.ObjectIdHex("4d88e15b60f486e428412dc9")
+	v := jsonType{Id: &id}
+	data, err := json.Marshal(&v)
+	c.Assert(err, IsNil)
+	c.Assert(string(data), Equals, `{"Id":"4d88e15b60f486e428412dc9"}`)
+}
+
+func (s *S) TestObjectIdJSONUnmarshaling(c *C) {
+	data := []byte(`{"Id":"4d88e15b60f486e428412dc9"}`)
+	v := jsonType{}
+	err := json.Unmarshal(data, &v)
+	c.Assert(err, IsNil)
+	c.Assert(*v.Id, Equals, bson.ObjectIdHex("4d88e15b60f486e428412dc9"))
+}
+
+func (s *S) TestObjectIdJSONUnmarshalingError(c *C) {
+	v := jsonType{}
+	err := json.Unmarshal([]byte(`{"Id":"4d88e15b60f486e428412dc9A"}`), &v)
+	c.Assert(err, ErrorMatches, `Invalid ObjectId in JSON: "4d88e15b60f486e428412dc9A"`)
+	err = json.Unmarshal([]byte(`{"Id":"4d88e15b60f486e428412dcZ"}`), &v)
+	c.Assert(err, ErrorMatches, `Invalid ObjectId in JSON: "4d88e15b60f486e428412dcZ" .*`)
+}
+
+// --------------------------------------------------------------------------
+// Some simple benchmarks.
+
+type BenchT struct {
+	A, B, C, D, E, F string
+}
+
+func BenchmarkUnmarhsalStruct(b *testing.B) {
+	v := BenchT{A: "A", D: "D", E: "E"}
+	data, err := bson.Marshal(&v)
+	if err != nil {
+		panic(err)
+	}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		err = bson.Unmarshal(data, &v)
+	}
+	if err != nil {
+		panic(err)
+	}
+}
+
+func BenchmarkUnmarhsalMap(b *testing.B) {
+	m := bson.M{"a": "a", "d": "d", "e": "e"}
+	data, err := bson.Marshal(&m)
+	if err != nil {
+		panic(err)
+	}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		err = bson.Unmarshal(data, &m)
+	}
+	if err != nil {
+		panic(err)
+	}
+}

=== added file 'bson/decode.go'
--- bson/decode.go	1970-01-01 00:00:00 +0000
+++ bson/decode.go	2013-04-03 09:16:27 +0000
@@ -0,0 +1,734 @@
+// BSON library for Go
+// 
+// Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+// 
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met: 
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this
+//    list of conditions and the following disclaimer. 
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution. 
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+// gobson - BSON library for Go.
+
+package bson
+
+import (
+	"fmt"
+	"math"
+	"net/url"
+	"reflect"
+	"sync"
+	"time"
+)
+
+type decoder struct {
+	in      []byte
+	i       int
+	docType reflect.Type
+}
+
+var typeM = reflect.TypeOf(M{})
+
+func newDecoder(in []byte) *decoder {
+	return &decoder{in, 0, typeM}
+}
+
+// --------------------------------------------------------------------------
+// Some helper functions.
+
+func corrupted() {
+	panic("Document is corrupted")
+}
+
+func settableValueOf(i interface{}) reflect.Value {
+	v := reflect.ValueOf(i)
+	sv := reflect.New(v.Type()).Elem()
+	sv.Set(v)
+	return sv
+}
+
+// --------------------------------------------------------------------------
+// Unmarshaling of documents.
+
+const (
+	setterUnknown = iota
+	setterNone
+	setterType
+	setterAddr
+)
+
+var setterStyle map[reflect.Type]int
+var setterIface reflect.Type
+var setterMutex sync.RWMutex
+
+func init() {
+	var iface Setter
+	setterIface = reflect.TypeOf(&iface).Elem()
+	setterStyle = make(map[reflect.Type]int)
+}
+
+func getSetter(outt reflect.Type, out reflect.Value) Setter {
+	setterMutex.RLock()
+	style := setterStyle[outt]
+	setterMutex.RUnlock()
+	if style == setterNone {
+		return nil
+	}
+	if style == setterUnknown {
+		setterMutex.Lock()
+		defer setterMutex.Unlock()
+		if outt.Implements(setterIface) {
+			setterStyle[outt] = setterType
+		} else if reflect.PtrTo(outt).Implements(setterIface) {
+			setterStyle[outt] = setterAddr
+		} else {
+			setterStyle[outt] = setterNone
+			return nil
+		}
+		style = setterStyle[outt]
+	}
+	if style == setterAddr {
+		if !out.CanAddr() {
+			return nil
+		}
+		out = out.Addr()
+	} else if outt.Kind() == reflect.Ptr && out.IsNil() {
+		out.Set(reflect.New(outt.Elem()))
+	}
+	return out.Interface().(Setter)
+}
+
+func (d *decoder) readDocTo(out reflect.Value) {
+	var elemType reflect.Type
+	outt := out.Type()
+	outk := outt.Kind()
+
+	for {
+		if outk == reflect.Ptr && out.IsNil() {
+			out.Set(reflect.New(outt.Elem()))
+		}
+		if setter := getSetter(outt, out); setter != nil {
+			var raw Raw
+			d.readDocTo(reflect.ValueOf(&raw))
+			err := setter.SetBSON(raw)
+			if _, ok := err.(*TypeError); err != nil && !ok {
+				panic(err)
+			}
+			return
+		}
+		if outk == reflect.Ptr {
+			out = out.Elem()
+			outt = out.Type()
+			outk = out.Kind()
+			continue
+		}
+		break
+	}
+
+	var fieldsMap map[string]fieldInfo
+	start := d.i
+
+	origout := out
+	if outk == reflect.Interface {
+		if d.docType.Kind() == reflect.Map {
+			mv := reflect.MakeMap(d.docType)
+			out.Set(mv)
+			out = mv
+		} else {
+			dv := reflect.New(d.docType).Elem()
+			out.Set(dv)
+			out = dv
+		}
+		outt = out.Type()
+		outk = outt.Kind()
+	}
+
+	docType := d.docType
+	switch outk {
+	case reflect.Map:
+		if outt.Key().Kind() != reflect.String {
+			panic("BSON map must have string keys. Got: " + outt.String())
+		}
+		elemType = outt.Elem()
+		if elemType == typeIface {
+			d.docType = outt
+		}
+		if out.IsNil() {
+			out.Set(reflect.MakeMap(out.Type()))
+		} else if out.Len() > 0 {
+			var none reflect.Value
+			for _, k := range out.MapKeys() {
+				out.SetMapIndex(k, none)
+			}
+		}
+	case reflect.Struct:
+		if outt != typeRaw {
+			sinfo, err := getStructInfo(out.Type())
+			if err != nil {
+				panic(err)
+			}
+			fieldsMap = sinfo.FieldsMap
+			out.Set(sinfo.Zero)
+		}
+	case reflect.Slice:
+		if outt.Elem() == typeDocElem {
+			origout.Set(d.readDocElems(outt))
+			return
+		}
+		fallthrough
+	default:
+		panic("Unsupported document type for unmarshalling: " + out.Type().String())
+	}
+
+	end := d.i - 4 + int(d.readInt32())
+	if end <= d.i || end > len(d.in) || d.in[end-1] != '\x00' {
+		corrupted()
+	}
+	for d.in[d.i] != '\x00' {
+		kind := d.readByte()
+		name := d.readCStr()
+		if d.i >= end {
+			corrupted()
+		}
+
+		switch outk {
+		case reflect.Map:
+			e := reflect.New(elemType).Elem()
+			if d.readElemTo(e, kind) {
+				out.SetMapIndex(reflect.ValueOf(name), e)
+			}
+		case reflect.Struct:
+			if outt == typeRaw {
+				d.readElemTo(blackHole, kind)
+			} else {
+				if info, ok := fieldsMap[name]; ok {
+					if info.Inline == nil {
+						d.readElemTo(out.Field(info.Num), kind)
+					} else {
+						d.readElemTo(out.FieldByIndex(info.Inline), kind)
+					}
+				} else {
+					d.dropElem(kind)
+				}
+			}
+		case reflect.Slice:
+		}
+
+		if d.i >= end {
+			corrupted()
+		}
+	}
+	d.i++ // '\x00'
+	if d.i != end {
+		corrupted()
+	}
+	d.docType = docType
+
+	if outt == typeRaw {
+		out.Set(reflect.ValueOf(Raw{0x03, d.in[start:d.i]}))
+	}
+}
+
+func (d *decoder) readArrayDocTo(out reflect.Value) {
+	end := d.i - 4 + int(d.readInt32())
+	if end <= d.i || end > len(d.in) || d.in[end-1] != '\x00' {
+		corrupted()
+	}
+	i := 0
+	l := out.Len()
+	for d.in[d.i] != '\x00' {
+		if i >= l {
+			panic("Length mismatch on array field")
+		}
+		kind := d.readByte()
+		for d.i < end && d.in[d.i] != '\x00' {
+			d.i++
+		}
+		if d.i >= end {
+			corrupted()
+		}
+		d.i++
+		d.readElemTo(out.Index(i), kind)
+		if d.i >= end {
+			corrupted()
+		}
+		i++
+	}
+	if i != l {
+		panic("Length mismatch on array field")
+	}
+	d.i++ // '\x00'
+	if d.i != end {
+		corrupted()
+	}
+}
+
+func (d *decoder) readSliceDoc(t reflect.Type) interface{} {
+	tmp := make([]reflect.Value, 0, 8)
+	elemType := t.Elem()
+
+	end := d.i - 4 + int(d.readInt32())
+	if end <= d.i || end > len(d.in) || d.in[end-1] != '\x00' {
+		corrupted()
+	}
+	for d.in[d.i] != '\x00' {
+		kind := d.readByte()
+		for d.i < end && d.in[d.i] != '\x00' {
+			d.i++
+		}
+		if d.i >= end {
+			corrupted()
+		}
+		d.i++
+		e := reflect.New(elemType).Elem()
+		if d.readElemTo(e, kind) {
+			tmp = append(tmp, e)
+		}
+		if d.i >= end {
+			corrupted()
+		}
+	}
+	d.i++ // '\x00'
+	if d.i != end {
+		corrupted()
+	}
+
+	n := len(tmp)
+	slice := reflect.MakeSlice(t, n, n)
+	for i := 0; i != n; i++ {
+		slice.Index(i).Set(tmp[i])
+	}
+	return slice.Interface()
+}
+
+var typeSlice = reflect.TypeOf([]interface{}{})
+var typeIface = typeSlice.Elem()
+
+func (d *decoder) readDocElems(typ reflect.Type) reflect.Value {
+	docType := d.docType
+	d.docType = typ
+	slice := make([]DocElem, 0, 8)
+	d.readDocWith(func(kind byte, name string) {
+		e := DocElem{Name: name}
+		v := reflect.ValueOf(&e.Value)
+		if d.readElemTo(v.Elem(), kind) {
+			slice = append(slice, e)
+		}
+	})
+	slicev := reflect.New(typ).Elem()
+	slicev.Set(reflect.ValueOf(slice))
+	d.docType = docType
+	return slicev
+}
+
+func (d *decoder) readDocWith(f func(kind byte, name string)) {
+	end := d.i - 4 + int(d.readInt32())
+	if end <= d.i || end > len(d.in) || d.in[end-1] != '\x00' {
+		corrupted()
+	}
+	for d.in[d.i] != '\x00' {
+		kind := d.readByte()
+		name := d.readCStr()
+		if d.i >= end {
+			corrupted()
+		}
+		f(kind, name)
+		if d.i >= end {
+			corrupted()
+		}
+	}
+	d.i++ // '\x00'
+	if d.i != end {
+		corrupted()
+	}
+}
+
+// --------------------------------------------------------------------------
+// Unmarshaling of individual elements within a document.
+
+var blackHole = settableValueOf(struct{}{})
+
+func (d *decoder) dropElem(kind byte) {
+	d.readElemTo(blackHole, kind)
+}
+
+// Attempt to decode an element from the document and put it into out.
+// If the types are not compatible, the returned ok value will be
+// false and out will be unchanged.
+func (d *decoder) readElemTo(out reflect.Value, kind byte) (good bool) {
+
+	start := d.i
+
+	if kind == '\x03' {
+		// Special case for documents. Delegate to readDocTo().
+		switch out.Kind() {
+		case reflect.Interface, reflect.Ptr, reflect.Struct, reflect.Map:
+			d.readDocTo(out)
+		default:
+			if _, ok := out.Interface().(D); ok {
+				out.Set(d.readDocElems(out.Type()))
+			} else {
+				d.readDocTo(blackHole)
+			}
+		}
+		return true
+	}
+
+	var in interface{}
+
+	switch kind {
+	case 0x01: // Float64
+		in = d.readFloat64()
+	case 0x02: // UTF-8 string
+		in = d.readStr()
+	case 0x03: // Document
+		panic("Can't happen. Handled above.")
+	case 0x04: // Array
+		outt := out.Type()
+		for outt.Kind() == reflect.Ptr {
+			outt = outt.Elem()
+		}
+		switch outt.Kind() {
+		case reflect.Array:
+			d.readArrayDocTo(out)
+			return true
+		case reflect.Slice:
+			in = d.readSliceDoc(outt)
+		default:
+			in = d.readSliceDoc(typeSlice)
+		}
+	case 0x05: // Binary
+		b := d.readBinary()
+		if b.Kind == 0x00 || b.Kind == 0x02 {
+			in = b.Data
+		} else {
+			in = b
+		}
+	case 0x06: // Undefined (obsolete, but still seen in the wild)
+		in = Undefined
+	case 0x07: // ObjectId
+		in = ObjectId(d.readBytes(12))
+	case 0x08: // Bool
+		in = d.readBool()
+	case 0x09: // Timestamp
+		// MongoDB handles timestamps as milliseconds.
+		i := d.readInt64()
+		if i == -62135596800000 {
+			in = time.Time{} // In UTC for convenience.
+		} else {
+			in = time.Unix(i/1e3, i%1e3*1e6)
+		}
+	case 0x0A: // Nil
+		in = nil
+	case 0x0B: // RegEx
+		in = d.readRegEx()
+	case 0x0D: // JavaScript without scope
+		in = JavaScript{Code: d.readStr()}
+	case 0x0E: // Symbol
+		in = Symbol(d.readStr())
+	case 0x0F: // JavaScript with scope
+		d.i += 4 // Skip length
+		js := JavaScript{d.readStr(), make(M)}
+		d.readDocTo(reflect.ValueOf(js.Scope))
+		in = js
+	case 0x10: // Int32
+		in = int(d.readInt32())
+	case 0x11: // Mongo-specific timestamp
+		in = MongoTimestamp(d.readInt64())
+	case 0x12: // Int64
+		in = d.readInt64()
+	case 0x7F: // Max key
+		in = MaxKey
+	case 0xFF: // Min key
+		in = MinKey
+	default:
+		panic(fmt.Sprintf("Unknown element kind (0x%02X)", kind))
+	}
+
+	outt := out.Type()
+
+	if outt == typeRaw {
+		out.Set(reflect.ValueOf(Raw{kind, d.in[start:d.i]}))
+		return true
+	}
+
+	if setter := getSetter(outt, out); setter != nil {
+		err := setter.SetBSON(Raw{kind, d.in[start:d.i]})
+		if err == SetZero {
+			out.Set(reflect.Zero(outt))
+			return true
+		}
+		if err == nil {
+			return true
+		}
+		if _, ok := err.(*TypeError); !ok {
+			panic(err)
+		}
+		return false
+	}
+
+	if in == nil {
+		out.Set(reflect.Zero(outt))
+		return true
+	}
+
+	outk := outt.Kind()
+
+	// Dereference and initialize pointer if necessary.
+	first := true
+	for outk == reflect.Ptr {
+		if !out.IsNil() {
+			out = out.Elem()
+		} else {
+			elem := reflect.New(outt.Elem())
+			if first {
+				// Only set if value is compatible.
+				first = false
+				defer func(out, elem reflect.Value) {
+					if good {
+						out.Set(elem)
+					}
+				}(out, elem)
+			} else {
+				out.Set(elem)
+			}
+			out = elem
+		}
+		outt = out.Type()
+		outk = outt.Kind()
+	}
+
+	inv := reflect.ValueOf(in)
+	if outt == inv.Type() {
+		out.Set(inv)
+		return true
+	}
+
+	switch outk {
+	case reflect.Interface:
+		out.Set(inv)
+		return true
+	case reflect.String:
+		switch inv.Kind() {
+		case reflect.String:
+			out.SetString(inv.String())
+			return true
+		case reflect.Slice:
+			if b, ok := in.([]byte); ok {
+				out.SetString(string(b))
+				return true
+			}
+		}
+	case reflect.Slice, reflect.Array:
+		// Remember, array (0x04) slices are built with the correct
+		// element type.  If we are here, must be a cross BSON kind
+		// conversion (e.g. 0x05 unmarshalling on string).
+		if outt.Elem().Kind() != reflect.Uint8 {
+			break
+		}
+		switch inv.Kind() {
+		case reflect.String:
+			slice := []byte(inv.String())
+			out.Set(reflect.ValueOf(slice))
+			return true
+		case reflect.Slice:
+			switch outt.Kind() {
+			case reflect.Array:
+				reflect.Copy(out, inv)
+			case reflect.Slice:
+				out.SetBytes(inv.Bytes())
+			}
+			return true
+		}
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		switch inv.Kind() {
+		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+			out.SetInt(inv.Int())
+			return true
+		case reflect.Float32, reflect.Float64:
+			out.SetInt(int64(inv.Float()))
+			return true
+		case reflect.Bool:
+			if inv.Bool() {
+				out.SetInt(1)
+			} else {
+				out.SetInt(0)
+			}
+			return true
+		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+			panic("Can't happen. No uint types in BSON?")
+		}
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		switch inv.Kind() {
+		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+			out.SetUint(uint64(inv.Int()))
+			return true
+		case reflect.Float32, reflect.Float64:
+			out.SetUint(uint64(inv.Float()))
+			return true
+		case reflect.Bool:
+			if inv.Bool() {
+				out.SetUint(1)
+			} else {
+				out.SetUint(0)
+			}
+			return true
+		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+			panic("Can't happen. No uint types in BSON.")
+		}
+	case reflect.Float32, reflect.Float64:
+		switch inv.Kind() {
+		case reflect.Float32, reflect.Float64:
+			out.SetFloat(inv.Float())
+			return true
+		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+			out.SetFloat(float64(inv.Int()))
+			return true
+		case reflect.Bool:
+			if inv.Bool() {
+				out.SetFloat(1)
+			} else {
+				out.SetFloat(0)
+			}
+			return true
+		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+			panic("Can't happen. No uint types in BSON?")
+		}
+	case reflect.Bool:
+		switch inv.Kind() {
+		case reflect.Bool:
+			out.SetBool(inv.Bool())
+			return true
+		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+			out.SetBool(inv.Int() != 0)
+			return true
+		case reflect.Float32, reflect.Float64:
+			out.SetBool(inv.Float() != 0)
+			return true
+		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+			panic("Can't happen. No uint types in BSON?")
+		}
+	case reflect.Struct:
+		if outt == typeURL && inv.Kind() == reflect.String {
+			u, err := url.Parse(inv.String())
+			if err != nil {
+				panic(err)
+			}
+			out.Set(reflect.ValueOf(u).Elem())
+			return true
+		}
+	}
+
+	return false
+}
+
+// --------------------------------------------------------------------------
+// Parsers of basic types.
+
+func (d *decoder) readRegEx() RegEx {
+	re := RegEx{}
+	re.Pattern = d.readCStr()
+	re.Options = d.readCStr()
+	return re
+}
+
+func (d *decoder) readBinary() Binary {
+	l := d.readInt32()
+	b := Binary{}
+	b.Kind = d.readByte()
+	b.Data = d.readBytes(l)
+	if b.Kind == 0x02 {
+		// Weird obsolete format with redundant length.
+		b.Data = b.Data[4:]
+	}
+	return b
+}
+
+func (d *decoder) readStr() string {
+	l := d.readInt32()
+	b := d.readBytes(l - 1)
+	if d.readByte() != '\x00' {
+		corrupted()
+	}
+	return string(b)
+}
+
+func (d *decoder) readCStr() string {
+	start := d.i
+	end := start
+	l := len(d.in)
+	for ; end != l; end++ {
+		if d.in[end] == '\x00' {
+			break
+		}
+	}
+	d.i = end + 1
+	if d.i > l {
+		corrupted()
+	}
+	return string(d.in[start:end])
+}
+
+func (d *decoder) readBool() bool {
+	if d.readByte() == 1 {
+		return true
+	}
+	return false
+}
+
+func (d *decoder) readFloat64() float64 {
+	return math.Float64frombits(uint64(d.readInt64()))
+}
+
+func (d *decoder) readInt32() int32 {
+	b := d.readBytes(4)
+	return int32((uint32(b[0]) << 0) |
+		(uint32(b[1]) << 8) |
+		(uint32(b[2]) << 16) |
+		(uint32(b[3]) << 24))
+}
+
+func (d *decoder) readInt64() int64 {
+	b := d.readBytes(8)
+	return int64((uint64(b[0]) << 0) |
+		(uint64(b[1]) << 8) |
+		(uint64(b[2]) << 16) |
+		(uint64(b[3]) << 24) |
+		(uint64(b[4]) << 32) |
+		(uint64(b[5]) << 40) |
+		(uint64(b[6]) << 48) |
+		(uint64(b[7]) << 56))
+}
+
+func (d *decoder) readByte() byte {
+	i := d.i
+	d.i++
+	if d.i > len(d.in) {
+		corrupted()
+	}
+	return d.in[i]
+}
+
+func (d *decoder) readBytes(length int32) []byte {
+	start := d.i
+	d.i += int(length)
+	if d.i > len(d.in) {
+		corrupted()
+	}
+	return d.in[start : start+int(length)]
+}

=== added file 'bson/encode.go'
--- bson/encode.go	1970-01-01 00:00:00 +0000
+++ bson/encode.go	2013-04-03 09:16:27 +0000
@@ -0,0 +1,430 @@
+// BSON library for Go
+// 
+// Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+// 
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met: 
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this
+//    list of conditions and the following disclaimer. 
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution. 
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+// gobson - BSON library for Go.
+
+package bson
+
+import (
+	"math"
+	"net/url"
+	"reflect"
+	"strconv"
+	"time"
+)
+
+// --------------------------------------------------------------------------
+// Some internal infrastructure.
+
+var (
+	typeBinary         = reflect.TypeOf(Binary{})
+	typeObjectId       = reflect.TypeOf(ObjectId(""))
+	typeSymbol         = reflect.TypeOf(Symbol(""))
+	typeMongoTimestamp = reflect.TypeOf(MongoTimestamp(0))
+	typeOrderKey       = reflect.TypeOf(MinKey)
+	typeDocElem        = reflect.TypeOf(DocElem{})
+	typeRaw            = reflect.TypeOf(Raw{})
+	typeURL            = reflect.TypeOf(url.URL{})
+	typeTime           = reflect.TypeOf(time.Time{})
+)
+
+const itoaCacheSize = 32
+
+var itoaCache []string
+
+func init() {
+	itoaCache = make([]string, itoaCacheSize)
+	for i := 0; i != itoaCacheSize; i++ {
+		itoaCache[i] = strconv.Itoa(i)
+	}
+}
+
+func itoa(i int) string {
+	if i < itoaCacheSize {
+		return itoaCache[i]
+	}
+	return strconv.Itoa(i)
+}
+
+// --------------------------------------------------------------------------
+// Marshaling of the document value itself.
+
+type encoder struct {
+	out []byte
+}
+
+func (e *encoder) addDoc(v reflect.Value) {
+	for {
+		if vi, ok := v.Interface().(Getter); ok {
+			getv, err := vi.GetBSON()
+			if err != nil {
+				panic(err)
+			}
+			v = reflect.ValueOf(getv)
+			continue
+		}
+		if v.Kind() == reflect.Ptr {
+			v = v.Elem()
+			continue
+		}
+		break
+	}
+
+	if v.Type() == typeRaw {
+		raw := v.Interface().(Raw)
+		if raw.Kind != 0x03 && raw.Kind != 0x00 {
+			panic("Attempted to unmarshal Raw kind " + strconv.Itoa(int(raw.Kind)) + " as a document")
+		}
+		e.addBytes(raw.Data...)
+		return
+	}
+
+	start := e.reserveInt32()
+
+	switch v.Kind() {
+	case reflect.Map:
+		e.addMap(v)
+	case reflect.Struct:
+		e.addStruct(v)
+	case reflect.Array, reflect.Slice:
+		e.addSlice(v)
+	default:
+		panic("Can't marshal " + v.Type().String() + " as a BSON document")
+	}
+
+	e.addBytes(0)
+	e.setInt32(start, int32(len(e.out)-start))
+}
+
+func (e *encoder) addMap(v reflect.Value) {
+	for _, k := range v.MapKeys() {
+		e.addElem(k.String(), v.MapIndex(k), false)
+	}
+}
+
+func (e *encoder) addStruct(v reflect.Value) {
+	sinfo, err := getStructInfo(v.Type())
+	if err != nil {
+		panic(err)
+	}
+	var value reflect.Value
+	for _, info := range sinfo.FieldsList {
+		if info.Inline == nil {
+			value = v.Field(info.Num)
+		} else {
+			value = v.FieldByIndex(info.Inline)
+		}
+		if info.OmitEmpty && isZero(value) {
+			continue
+		}
+		e.addElem(info.Key, value, info.MinSize)
+	}
+}
+
+func isZero(v reflect.Value) bool {
+	switch v.Kind() {
+	case reflect.String:
+		return len(v.String()) == 0
+	case reflect.Ptr, reflect.Interface:
+		return v.IsNil()
+	case reflect.Slice:
+		return v.Len() == 0
+	case reflect.Map:
+		return v.Len() == 0
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return v.Int() == 0
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		return v.Uint() == 0
+	case reflect.Float32, reflect.Float64:
+		return v.Float() == 0
+	case reflect.Bool:
+		return !v.Bool()
+	case reflect.Struct:
+		if v.Type() == typeTime {
+			return v.Interface().(time.Time).IsZero()
+		}
+	}
+	return false
+}
+
+func (e *encoder) addSlice(v reflect.Value) {
+	if d, ok := v.Interface().(D); ok {
+		for _, elem := range d {
+			e.addElem(elem.Name, reflect.ValueOf(elem.Value), false)
+		}
+	} else if v.Type().Elem() == typeDocElem {
+		l := v.Len()
+		for i := 0; i < l; i++ {
+			elem := v.Index(i).Interface().(DocElem)
+			e.addElem(elem.Name, reflect.ValueOf(elem.Value), false)
+		}
+	} else {
+		l := v.Len()
+		for i := 0; i < l; i++ {
+			e.addElem(itoa(i), v.Index(i), false)
+		}
+	}
+}
+
+// --------------------------------------------------------------------------
+// Marshaling of elements in a document.
+
+func (e *encoder) addElemName(kind byte, name string) {
+	e.addBytes(kind)
+	e.addBytes([]byte(name)...)
+	e.addBytes(0)
+}
+
+func (e *encoder) addElem(name string, v reflect.Value, minSize bool) {
+
+	if !v.IsValid() {
+		e.addElemName('\x0A', name)
+		return
+	}
+
+	if getter, ok := v.Interface().(Getter); ok {
+		getv, err := getter.GetBSON()
+		if err != nil {
+			panic(err)
+		}
+		e.addElem(name, reflect.ValueOf(getv), minSize)
+		return
+	}
+
+	switch v.Kind() {
+
+	case reflect.Interface:
+		e.addElem(name, v.Elem(), minSize)
+
+	case reflect.Ptr:
+		e.addElem(name, v.Elem(), minSize)
+
+	case reflect.String:
+		s := v.String()
+		switch v.Type() {
+		case typeObjectId:
+			if len(s) != 12 {
+				panic("ObjectIDs must be exactly 12 bytes long (got " +
+					strconv.Itoa(len(s)) + ")")
+			}
+			e.addElemName('\x07', name)
+			e.addBytes([]byte(s)...)
+		case typeSymbol:
+			e.addElemName('\x0E', name)
+			e.addStr(s)
+		default:
+			e.addElemName('\x02', name)
+			e.addStr(s)
+		}
+
+	case reflect.Float32, reflect.Float64:
+		e.addElemName('\x01', name)
+		e.addInt64(int64(math.Float64bits(v.Float())))
+
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		u := v.Uint()
+		if int64(u) < 0 {
+			panic("BSON has no uint64 type, and value is too large to fit correctly in an int64")
+		} else if u <= math.MaxInt32 && (minSize || v.Kind() <= reflect.Uint32) {
+			e.addElemName('\x10', name)
+			e.addInt32(int32(u))
+		} else {
+			e.addElemName('\x12', name)
+			e.addInt64(int64(u))
+		}
+
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		if v.Type().Kind() <= reflect.Int32 {
+			e.addElemName('\x10', name)
+			e.addInt32(int32(v.Int()))
+		} else {
+			switch v.Type() {
+			case typeMongoTimestamp:
+				e.addElemName('\x11', name)
+				e.addInt64(v.Int())
+
+			case typeOrderKey:
+				if v.Int() == int64(MaxKey) {
+					e.addElemName('\x7F', name)
+				} else {
+					e.addElemName('\xFF', name)
+				}
+
+			default:
+				i := v.Int()
+				if minSize && i >= math.MinInt32 && i <= math.MaxInt32 {
+					// It fits into an int32, encode as such.
+					e.addElemName('\x10', name)
+					e.addInt32(int32(i))
+				} else {
+					e.addElemName('\x12', name)
+					e.addInt64(i)
+				}
+			}
+		}
+
+	case reflect.Bool:
+		e.addElemName('\x08', name)
+		if v.Bool() {
+			e.addBytes(1)
+		} else {
+			e.addBytes(0)
+		}
+
+	case reflect.Map:
+		e.addElemName('\x03', name)
+		e.addDoc(v)
+
+	case reflect.Slice:
+		vt := v.Type()
+		et := vt.Elem()
+		if et.Kind() == reflect.Uint8 {
+			e.addElemName('\x05', name)
+			e.addBinary('\x00', v.Bytes())
+		} else if et == typeDocElem {
+			e.addElemName('\x03', name)
+			e.addDoc(v)
+		} else {
+			e.addElemName('\x04', name)
+			e.addDoc(v)
+		}
+
+	case reflect.Array:
+		et := v.Type().Elem()
+		if et.Kind() == reflect.Uint8 {
+			e.addElemName('\x05', name)
+			e.addBinary('\x00', v.Slice(0, v.Len()).Interface().([]byte))
+		} else {
+			e.addElemName('\x04', name)
+			e.addDoc(v)
+		}
+
+	case reflect.Struct:
+		switch s := v.Interface().(type) {
+
+		case Raw:
+			kind := s.Kind
+			if kind == 0x00 {
+				kind = 0x03
+			}
+			e.addElemName(kind, name)
+			e.addBytes(s.Data...)
+
+		case Binary:
+			e.addElemName('\x05', name)
+			e.addBinary(s.Kind, s.Data)
+
+		case RegEx:
+			e.addElemName('\x0B', name)
+			e.addCStr(s.Pattern)
+			e.addCStr(s.Options)
+
+		case JavaScript:
+			if s.Scope == nil {
+				e.addElemName('\x0D', name)
+				e.addStr(s.Code)
+			} else {
+				e.addElemName('\x0F', name)
+				start := e.reserveInt32()
+				e.addStr(s.Code)
+				e.addDoc(reflect.ValueOf(s.Scope))
+				e.setInt32(start, int32(len(e.out)-start))
+			}
+
+		case time.Time:
+			// MongoDB handles timestamps as milliseconds.
+			e.addElemName('\x09', name)
+			e.addInt64(s.Unix() * 1000 + int64(s.Nanosecond() / 1e6))
+
+		case url.URL:
+			e.addElemName('\x02', name)
+			e.addStr(s.String())
+
+		case undefined:
+			e.addElemName('\x06', name)
+
+		default:
+			e.addElemName('\x03', name)
+			e.addDoc(v)
+		}
+
+	default:
+		panic("Can't marshal " + v.Type().String() + " in a BSON document")
+	}
+}
+
+// --------------------------------------------------------------------------
+// Marshaling of base types.
+
+func (e *encoder) addBinary(subtype byte, v []byte) {
+	if subtype == 0x02 {
+		// Wonder how that brilliant idea came to life. Obsolete, luckily.
+		e.addInt32(int32(len(v) + 4))
+		e.addBytes(subtype)
+		e.addInt32(int32(len(v)))
+	} else {
+		e.addInt32(int32(len(v)))
+		e.addBytes(subtype)
+	}
+	e.addBytes(v...)
+}
+
+func (e *encoder) addStr(v string) {
+	e.addInt32(int32(len(v) + 1))
+	e.addCStr(v)
+}
+
+func (e *encoder) addCStr(v string) {
+	e.addBytes([]byte(v)...)
+	e.addBytes(0)
+}
+
+func (e *encoder) reserveInt32() (pos int) {
+	pos = len(e.out)
+	e.addBytes(0, 0, 0, 0)
+	return pos
+}
+
+func (e *encoder) setInt32(pos int, v int32) {
+	e.out[pos+0] = byte(v)
+	e.out[pos+1] = byte(v >> 8)
+	e.out[pos+2] = byte(v >> 16)
+	e.out[pos+3] = byte(v >> 24)
+}
+
+func (e *encoder) addInt32(v int32) {
+	u := uint32(v)
+	e.addBytes(byte(u), byte(u>>8), byte(u>>16), byte(u>>24))
+}
+
+func (e *encoder) addInt64(v int64) {
+	u := uint64(v)
+	e.addBytes(byte(u), byte(u>>8), byte(u>>16), byte(u>>24),
+		byte(u>>32), byte(u>>40), byte(u>>48), byte(u>>56))
+}
+
+func (e *encoder) addBytes(v ...byte) {
+	e.out = append(e.out, v...)
+}

=== added file 'cluster.go'
--- cluster.go	1970-01-01 00:00:00 +0000
+++ cluster.go	2013-04-03 09:16:27 +0000
@@ -0,0 +1,504 @@
+// mgo - MongoDB driver for Go
+// 
+// Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+// 
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met: 
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this
+//    list of conditions and the following disclaimer. 
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution. 
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+package mgo
+
+import (
+	"errors"
+	"sync"
+	"time"
+)
+
+// ---------------------------------------------------------------------------
+// Mongo cluster encapsulation.
+//
+// A cluster enables the communication with one or more servers participating
+// in a mongo cluster.  This works with individual servers, a replica set,
+// a replica pair, one or multiple mongos routers, etc.
+
+type mongoCluster struct {
+	sync.RWMutex
+	serverSynced sync.Cond
+	userSeeds    []string
+	dynaSeeds    []string
+	servers      mongoServers
+	masters      mongoServers
+	references   int
+	syncing      bool
+	direct       bool
+	cachedIndex  map[string]bool
+	sync         chan bool
+	dial         dialer
+}
+
+func newCluster(userSeeds []string, direct bool, dial dialer) *mongoCluster {
+	cluster := &mongoCluster{
+		userSeeds: userSeeds,
+		references: 1,
+		direct: direct,
+		dial: dial,
+	}
+	cluster.serverSynced.L = cluster.RWMutex.RLocker()
+	cluster.sync = make(chan bool, 1)
+	go cluster.syncServersLoop()
+	return cluster
+}
+
+// Acquire increases the reference count for the cluster.
+func (cluster *mongoCluster) Acquire() {
+	cluster.Lock()
+	cluster.references++
+	debugf("Cluster %p acquired (refs=%d)", cluster, cluster.references)
+	cluster.Unlock()
+}
+
+// Release decreases the reference count for the cluster. Once
+// it reaches zero, all servers will be closed.
+func (cluster *mongoCluster) Release() {
+	cluster.Lock()
+	if cluster.references == 0 {
+		panic("cluster.Release() with references == 0")
+	}
+	cluster.references--
+	debugf("Cluster %p released (refs=%d)", cluster, cluster.references)
+	if cluster.references == 0 {
+		for _, server := range cluster.servers.Slice() {
+			server.Close()
+		}
+		// Wake up the sync loop so it can die.
+		cluster.syncServers()
+	}
+	cluster.Unlock()
+}
+
+func (cluster *mongoCluster) LiveServers() (servers []string) {
+	cluster.RLock()
+	for _, serv := range cluster.servers.Slice() {
+		servers = append(servers, serv.Addr)
+	}
+	cluster.RUnlock()
+	return servers
+}
+
+func (cluster *mongoCluster) removeServer(server *mongoServer) {
+	cluster.Lock()
+	cluster.masters.Remove(server)
+	other := cluster.servers.Remove(server)
+	cluster.Unlock()
+	if other != nil {
+		other.Close()
+		log("Removed server ", server.Addr, " from cluster.")
+	}
+	server.Close()
+}
+
+type isMasterResult struct {
+	IsMaster  bool
+	Secondary bool
+	Primary   string
+	Hosts     []string
+	Passives  []string
+}
+
+func (cluster *mongoCluster) syncServer(server *mongoServer) (hosts []string, err error) {
+	addr := server.Addr
+	log("SYNC Processing ", addr, "...")
+
+	var result isMasterResult
+	var tryerr error
+	for retry := 0; ; retry++ {
+		if retry == 3 {
+			return nil, tryerr
+		}
+
+		socket, err := server.AcquireSocket(0)
+		if err != nil {
+			tryerr = err
+			logf("SYNC Failed to get socket to %s: %v", addr, err)
+			continue
+		}
+
+		// Monotonic will let us talk to a slave and still hold the socket.
+		session := newSession(Monotonic, cluster, 10 * time.Second)
+		session.setSocket(socket)
+
+		// session holds the socket now.
+		socket.Release()
+
+		err = session.Run("ismaster", &result)
+		session.Close()
+		if err != nil {
+			tryerr = err
+			logf("SYNC Command 'ismaster' to %s failed: %v", addr, err)
+			continue
+		}
+		debugf("SYNC Result of 'ismaster' from %s: %#v", addr, result)
+		break
+	}
+
+	if result.IsMaster {
+		debugf("SYNC %s is a master.", addr)
+		// Made an incorrect assumption above, so fix stats.
+		stats.conn(-1, false)
+		server.SetMaster(true)
+		stats.conn(+1, true)
+	} else if result.Secondary {
+		debugf("SYNC %s is a slave.", addr)
+	} else if cluster.direct {
+		logf("SYNC %s in unknown state. Pretending it's a slave due to direct connection.", addr)
+	} else {
+		logf("SYNC %s is neither a master nor a slave.", addr)
+		// Made an incorrect assumption above, so fix stats.
+		stats.conn(-1, false)
+		return nil, errors.New(addr + " is not a master nor slave")
+	}
+
+	hosts = make([]string, 0, 1+len(result.Hosts)+len(result.Passives))
+	if result.Primary != "" {
+		// First in the list to speed up master discovery.
+		hosts = append(hosts, result.Primary)
+	}
+	hosts = append(hosts, result.Hosts...)
+	hosts = append(hosts, result.Passives...)
+
+	debugf("SYNC %s knows about the following peers: %#v", addr, hosts)
+	return hosts, nil
+}
+
+func (cluster *mongoCluster) mergeServer(server *mongoServer) {
+	cluster.Lock()
+	previous := cluster.servers.Search(server)
+	isMaster := server.IsMaster()
+	if previous == nil {
+		cluster.servers.Add(server)
+		if isMaster {
+			cluster.masters.Add(server)
+			log("SYNC Adding ", server.Addr, " to cluster as a master.")
+		} else {
+			log("SYNC Adding ", server.Addr, " to cluster as a slave.")
+		}
+	} else {
+		if isMaster != previous.IsMaster() {
+			if isMaster {
+				log("SYNC Server ", server.Addr, " is now a master.")
+				cluster.masters.Add(previous)
+			} else {
+				log("SYNC Server ", server.Addr, " is now a slave.")
+				cluster.masters.Remove(previous)
+			}
+		}
+		previous.Merge(server)
+	}
+	debugf("SYNC Broadcasting availability of server %s", server.Addr)
+	cluster.serverSynced.Broadcast()
+	cluster.Unlock()
+}
+
+func (cluster *mongoCluster) getKnownAddrs() []string {
+	cluster.RLock()
+	max := len(cluster.userSeeds) + len(cluster.dynaSeeds) + cluster.servers.Len()
+	seen := make(map[string]bool, max)
+	known := make([]string, 0, max)
+
+	add := func(addr string) {
+		if _, found := seen[addr]; !found {
+			seen[addr] = true
+			known = append(known, addr)
+		}
+	}
+
+	for _, addr := range cluster.userSeeds {
+		add(addr)
+	}
+	for _, addr := range cluster.dynaSeeds {
+		add(addr)
+	}
+	for _, serv := range cluster.servers.Slice() {
+		add(serv.Addr)
+	}
+	cluster.RUnlock()
+
+	return known
+}
+
+// syncServers injects a value into the cluster.sync channel to force
+// an iteration of the syncServersLoop function.
+func (cluster *mongoCluster) syncServers() {
+	select {
+	case cluster.sync <- true:
+	default:
+	}
+}
+
+// How long to wait for a checkup of the cluster topology if nothing
+// else kicks a synchronization before that.
+const syncServersDelay = 3 * time.Minute
+
+// syncServersLoop loops while the cluster is alive to keep its idea of
+// the server topology up-to-date. It must be called just once from
+// newCluster.  The loop iterates once syncServersDelay has passed, or
+// if somebody injects a value into the cluster.sync channel to force a
+// synchronization.  A loop iteration will contact all servers in
+// parallel, ask them about known peers and their own role within the
+// cluster, and then attempt to do the same with all the peers
+// retrieved.
+func (cluster *mongoCluster) syncServersLoop() {
+	for {
+		debugf("SYNC Cluster %p is starting a sync loop iteration.", cluster)
+
+		cluster.Lock()
+		if cluster.references == 0 {
+			cluster.Unlock()
+			break
+		}
+		cluster.references++ // Keep alive while syncing.
+		direct := cluster.direct
+		cluster.Unlock()
+
+		cluster.syncServersIteration(direct)
+
+		// We just synchronized, so consume any outstanding requests.
+		select {
+		case <-cluster.sync:
+		default:
+		}
+
+		cluster.Release()
+
+		// Hold off before allowing another sync. No point in
+		// burning CPU looking for down servers.
+		time.Sleep(5e8)
+
+		cluster.Lock()
+		if cluster.references == 0 {
+			cluster.Unlock()
+			break
+		}
+		// Poke all waiters so they have a chance to timeout or
+		// restart syncing if they wish to.
+		cluster.serverSynced.Broadcast()
+		// Check if we have to restart immediately either way.
+		restart := !direct && cluster.masters.Empty() || cluster.servers.Empty()
+		cluster.Unlock()
+
+		if restart {
+			log("SYNC No masters found. Will synchronize again.")
+			continue
+		}
+
+		debugf("SYNC Cluster %p waiting for next requested or scheduled sync.", cluster)
+
+		// Hold off until somebody explicitly requests a synchronization
+		// or it's time to check for a cluster topology change again.
+		select {
+		case <-cluster.sync:
+		case <-time.After(syncServersDelay):
+		}
+	}
+	debugf("SYNC Cluster %p is stopping its sync loop.", cluster)
+}
+
+func (cluster *mongoCluster) syncServersIteration(direct bool) {
+	log("SYNC Starting full topology synchronization...")
+
+	var wg sync.WaitGroup
+	var m sync.Mutex
+	mergePending := make(map[string]*mongoServer)
+	mergeRequested := make(map[string]bool)
+	seen := make(map[string]bool)
+	goodSync := false
+
+	var spawnSync func(addr string, byMaster bool)
+	spawnSync = func(addr string, byMaster bool) {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+
+			server, err := newServer(addr, cluster.sync, cluster.dial)
+			if err != nil {
+				log("SYNC Failed to start sync of ", addr, ": ", err.Error())
+				return
+			}
+
+			m.Lock()
+			if byMaster {
+				if s, found := mergePending[server.ResolvedAddr]; found {
+					delete(mergePending, server.ResolvedAddr)
+					m.Unlock()
+					cluster.mergeServer(s)
+					return
+				}
+				mergeRequested[server.ResolvedAddr] = true
+			}
+			if seen[server.ResolvedAddr] {
+				m.Unlock()
+				return
+			}
+			seen[server.ResolvedAddr] = true
+			m.Unlock()
+
+			hosts, err := cluster.syncServer(server)
+			if err == nil {
+				isMaster := server.IsMaster()
+				if !direct {
+					for _, addr := range hosts {
+						spawnSync(addr, isMaster)
+					}
+				}
+
+				m.Lock()
+				merge := direct || isMaster
+				if mergeRequested[server.ResolvedAddr] {
+					merge = true
+				} else if !merge {
+					mergePending[server.ResolvedAddr] = server
+				}
+				if merge {
+					goodSync = true
+				}
+				m.Unlock()
+				if merge {
+					cluster.mergeServer(server)
+				}
+			} else {
+				server.Close()
+			}
+		}()
+	}
+
+	for _, addr := range cluster.getKnownAddrs() {
+		spawnSync(addr, false)
+	}
+	wg.Wait()
+
+	for _, server := range mergePending {
+		if goodSync {
+			cluster.removeServer(server)
+		} else {
+			server.Close()
+		}
+	}
+
+	cluster.Lock()
+	ml := cluster.masters.Len()
+	logf("SYNC Synchronization completed: %d master(s) and %d slave(s) alive.", ml, cluster.servers.Len()-ml)
+
+	// Update dynamic seeds, but only if we have any good servers. Otherwise,
+	// leave them alone for better chances of a successful sync in the future.
+	if goodSync {
+		dynaSeeds := make([]string, cluster.servers.Len())
+		for i, server := range cluster.servers.Slice() {
+			dynaSeeds[i] = server.Addr
+		}
+		cluster.dynaSeeds = dynaSeeds
+		debugf("SYNC New dynamic seeds: %#v\n", dynaSeeds)
+	}
+	cluster.Unlock()
+}
+
+var socketsPerServer = 4096
+
+// AcquireSocket returns a socket to a server in the cluster.  If slaveOk is
+// true, it will attempt to return a socket to a slave server.  If it is
+// false, the socket will necessarily be to a master server.
+func (cluster *mongoCluster) AcquireSocket(slaveOk bool, syncTimeout time.Duration) (s *mongoSocket, err error) {
+	var started time.Time
+	warnedLimit := false
+	for {
+		cluster.RLock()
+		for {
+			ml := cluster.masters.Len()
+			sl := cluster.servers.Len()
+			debugf("Cluster has %d known masters and %d known slaves.", ml, sl-ml)
+			if ml > 0 || slaveOk && sl > 0 {
+				break
+			}
+			if started.IsZero() {
+				started = time.Now() // Initialize after fast path above.
+			} else if syncTimeout != 0 && started.Before(time.Now().Add(-syncTimeout)) {
+				cluster.RUnlock()
+				return nil, errors.New("no reachable servers")
+			}
+			log("Waiting for servers to synchronize...")
+			cluster.syncServers()
+
+			// Remember: this will release and reacquire the lock.
+			cluster.serverSynced.Wait()
+		}
+
+		var server *mongoServer
+		if slaveOk {
+			server = cluster.servers.MostAvailable()
+		} else {
+			server = cluster.masters.MostAvailable()
+		}
+		cluster.RUnlock()
+
+		s, err = server.AcquireSocket(socketsPerServer)
+		if err == errSocketLimit {
+			if !warnedLimit {
+				log("WARNING: Per-server connection limit reached.")
+			}
+			time.Sleep(1e8)
+			continue
+		}
+		if err != nil {
+			cluster.removeServer(server)
+			cluster.syncServers()
+			continue
+		}
+		return s, nil
+	}
+	panic("unreached")
+}
+
+func (cluster *mongoCluster) CacheIndex(cacheKey string, exists bool) {
+	cluster.Lock()
+	if cluster.cachedIndex == nil {
+		cluster.cachedIndex = make(map[string]bool)
+	}
+	if exists {
+		cluster.cachedIndex[cacheKey] = true
+	} else {
+		delete(cluster.cachedIndex, cacheKey)
+	}
+	cluster.Unlock()
+}
+
+func (cluster *mongoCluster) HasCachedIndex(cacheKey string) (result bool) {
+	cluster.RLock()
+	if cluster.cachedIndex != nil {
+		result = cluster.cachedIndex[cacheKey]
+	}
+	cluster.RUnlock()
+	return
+}
+
+func (cluster *mongoCluster) ResetIndexCache() {
+	cluster.Lock()
+	cluster.cachedIndex = make(map[string]bool)
+	cluster.Unlock()
+}

=== added file 'cluster_test.go'
--- cluster_test.go	1970-01-01 00:00:00 +0000
+++ cluster_test.go	2013-04-03 09:16:27 +0000
@@ -0,0 +1,1108 @@
+// mgo - MongoDB driver for Go
+// 
+// Copyright (c) 2010-2012 - Gustavo Niemeyer <[e-mail]>
+// 
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met: 
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this
+//    list of conditions and the following disclaimer. 
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution. 
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+package mgo_test
+
+import (
+	"fmt"
+	"io"
+	. "launchpad.net/gocheck"
+	"labix.org/v2/mgo"
+	"labix.org/v2/mgo/bson"
+	"net"
+	"strings"
+	"time"
+)
+
+func (s *S) TestNewSession(c *C) {
+	session, err := mgo.Dial("localhost:40001")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	// Do a dummy operation to wait for connection.
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"_id": 1})
+	c.Assert(err, IsNil)
+
+	// Tweak safety and query settings to ensure other has copied those.
+	session.SetSafe(nil)
+	session.SetBatch(-1)
+	other := session.New()
+	defer other.Close()
+	session.SetSafe(&mgo.Safe{})
+
+	// Clone was copied while session was unsafe, so no errors.
+	otherColl := other.DB("mydb").C("mycoll")
+	err = otherColl.Insert(M{"_id": 1})
+	c.Assert(err, IsNil)
+
+	// Original session was made safe again.
+	err = coll.Insert(M{"_id": 1})
+	c.Assert(err, NotNil)
+
+	// With New(), each session has its own socket now.
+	stats := mgo.GetStats()
+	c.Assert(stats.MasterConns, Equals, 2)
+	c.Assert(stats.SocketsInUse, Equals, 2)
+
+	// Ensure query parameters were cloned.
+	err = otherColl.Insert(M{"_id": 2})
+	c.Assert(err, IsNil)
+
+	// Ping the database to ensure the nonce has been received already.
+	c.Assert(other.Ping(), IsNil)
+
+	mgo.ResetStats()
+
+	iter := otherColl.Find(M{}).Iter()
+	c.Assert(err, IsNil)
+
+	m := M{}
+	ok := iter.Next(m)
+	c.Assert(ok, Equals, true)
+	err = iter.Err()
+	c.Assert(err, IsNil)
+
+	// If Batch(-1) is in effect, a single document must have been received.
+	stats = mgo.GetStats()
+	c.Assert(stats.ReceivedDocs, Equals, 1)
+}
+
+func (s *S) TestCloneSession(c *C) {
+	session, err := mgo.Dial("localhost:40001")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	// Do a dummy operation to wait for connection.
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"_id": 1})
+	c.Assert(err, IsNil)
+
+	// Tweak safety and query settings to ensure clone is copying those.
+	session.SetSafe(nil)
+	session.SetBatch(-1)
+	clone := session.Clone()
+	defer clone.Close()
+	session.SetSafe(&mgo.Safe{})
+
+	// Clone was copied while session was unsafe, so no errors.
+	cloneColl := clone.DB("mydb").C("mycoll")
+	err = cloneColl.Insert(M{"_id": 1})
+	c.Assert(err, IsNil)
+
+	// Original session was made safe again.
+	err = coll.Insert(M{"_id": 1})
+	c.Assert(err, NotNil)
+
+	// With Clone(), same socket is shared between sessions now.
+	stats := mgo.GetStats()
+	c.Assert(stats.SocketsInUse, Equals, 1)
+	c.Assert(stats.SocketRefs, Equals, 2)
+
+	// Refreshing one of them should let the original socket go,
+	// while preserving the safety settings.
+	clone.Refresh()
+	err = cloneColl.Insert(M{"_id": 1})
+	c.Assert(err, IsNil)
+
+	// Must have used another connection now.
+	stats = mgo.GetStats()
+	c.Assert(stats.SocketsInUse, Equals, 2)
+	c.Assert(stats.SocketRefs, Equals, 2)
+
+	// Ensure query parameters were cloned.
+	err = cloneColl.Insert(M{"_id": 2})
+	c.Assert(err, IsNil)
+
+	// Ping the database to ensure the nonce has been received already.
+	c.Assert(clone.Ping(), IsNil)
+
+	mgo.ResetStats()
+
+	iter := cloneColl.Find(M{}).Iter()
+	c.Assert(err, IsNil)
+
+	m := M{}
+	ok := iter.Next(m)
+	c.Assert(ok, Equals, true)
+	err = iter.Err()
+	c.Assert(err, IsNil)
+
+	// If Batch(-1) is in effect, a single document must have been received.
+	stats = mgo.GetStats()
+	c.Assert(stats.ReceivedDocs, Equals, 1)
+}
+
+func (s *S) TestSetModeStrong(c *C) {
+	session, err := mgo.Dial("localhost:40012")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	session.SetMode(mgo.Monotonic, false)
+	session.SetMode(mgo.Strong, false)
+
+	c.Assert(session.Mode(), Equals, mgo.Strong)
+
+	result := M{}
+	cmd := session.DB("admin").C("$cmd")
+	err = cmd.Find(M{"ismaster": 1}).One(&result)
+	c.Assert(err, IsNil)
+	c.Assert(result["ismaster"], Equals, true)
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"a": 1})
+	c.Assert(err, IsNil)
+
+	// Wait since the sync also uses sockets.
+	for len(session.LiveServers()) != 3 {
+		c.Log("Waiting for cluster sync to finish...")
+		time.Sleep(5e8)
+	}
+
+	stats := mgo.GetStats()
+	c.Assert(stats.MasterConns, Equals, 1)
+	c.Assert(stats.SlaveConns, Equals, 2)
+	c.Assert(stats.SocketsInUse, Equals, 1)
+
+	session.SetMode(mgo.Strong, true)
+
+	stats = mgo.GetStats()
+	c.Assert(stats.SocketsInUse, Equals, 0)
+}
+
+func (s *S) TestSetModeMonotonic(c *C) {
+	// Must necessarily connect to a slave, otherwise the
+	// master connection will be available first.
+	session, err := mgo.Dial("localhost:40012")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	session.SetMode(mgo.Monotonic, false)
+
+	c.Assert(session.Mode(), Equals, mgo.Monotonic)
+
+	result := M{}
+	cmd := session.DB("admin").C("$cmd")
+	err = cmd.Find(M{"ismaster": 1}).One(&result)
+	c.Assert(err, IsNil)
+	c.Assert(result["ismaster"], Equals, false)
+
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"a": 1})
+	c.Assert(err, IsNil)
+
+	result = M{}
+	err = cmd.Find(M{"ismaster": 1}).One(&result)
+	c.Assert(err, IsNil)
+	c.Assert(result["ismaster"], Equals, true)
+
+	// Wait since the sync also uses sockets.
+	for len(session.LiveServers()) != 3 {
+		c.Log("Waiting for cluster sync to finish...")
+		time.Sleep(5e8)
+	}
+
+	stats := mgo.GetStats()
+	c.Assert(stats.MasterConns, Equals, 1)
+	c.Assert(stats.SlaveConns, Equals, 2)
+	c.Assert(stats.SocketsInUse, Equals, 2)
+
+	session.SetMode(mgo.Monotonic, true)
+
+	stats = mgo.GetStats()
+	c.Assert(stats.SocketsInUse, Equals, 0)
+}
+
+func (s *S) TestSetModeMonotonicAfterStrong(c *C) {
+	// Test that a strong session shifting to a monotonic
+	// one preserves the socket untouched.
+
+	session, err := mgo.Dial("localhost:40012")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	// Insert something to force a connection to the master.
+	coll := session.DB("mydb").C("mycoll")
+	err = coll.Insert(M{"a": 1})
+	c.Assert(err, IsNil)
+
+	session.SetMode(mgo.Monotonic, false)
+
+	// Wait since the sync also uses sockets.
+	for len(session.LiveServers()) != 3 {
+		c.Log("Waiting for cluster sync to finish...")
+		time.Sleep(5e8)
+	}
+
+	// Master socket should still be reserved.
+	stats := mgo.GetStats()
+	c.Assert(stats.SocketsInUse, Equals, 1)
+
+	// Confirm it's the master even though it's Monotonic by now.
+	result := M{}
+	cmd := session.DB("admin").C("$cmd")
+	err = cmd.Find(M{"ismaster": 1}).One(&result)
+	c.Assert(err, IsNil)
+	c.Assert(result["ismaster"], Equals, true)
+}
+
+func (s *S) TestSetModeStrongAfterMonotonic(c *C) {
+	// Test that shifting from Monotonic to Strong while
+	// using a slave socket will keep the socket reserved
+	// until the master socket is necessary, so that no
+	// switch over occurs unless it's actually necessary.
+
+	// Must necessarily connect to a slave, otherwise the
+	// master connection will be available first.
+	session, err := mgo.Dial("localhost:40012")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	session.SetMode(mgo.Monotonic, false)
+
+	// Ensure we're talking to a slave, and reserve the socket.
+	result := M{}
+	err = session.Run("ismaster", &result)
+	c.Assert(err, IsNil)
+	c.Assert(result["ismaster"], Equals, false)
+
+	// Switch to a Strong session.
+	session.SetMode(mgo.Strong, false)
+
+	// Wait since the sync also uses sockets.
+	for len(session.LiveServers()) != 3 {
+		c.Log("Waiting for cluster sync to finish...")
+		time.Sleep(5e8)
+	}
+
+	// Slave socket should still be reserved.
+	stats := mgo.GetStats()
+	c.Assert(stats.SocketsInUse, Equals, 1)
+
+	// But any operation will switch it to the master.
+	result = M{}
+	err = session.Run("ismaster", &result)
+	c.Assert(err, IsNil)
+	c.Assert(result["ismaster"], Equals, true)
+}
+
+func (s *S) TestSetModeMonotonicWriteOnIteration(c *C) {
+	// Must necessarily connect to a slave, otherwise the
+	// master connection will be available first.
+	session, err := mgo.Dial("localhost:40012")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	session.SetMode(mgo.Monotonic, false)
+
+	c.Assert(session.Mode(), Equals, mgo.Monotonic)
+
+	coll1 := session.DB("mydb").C("mycoll1")
+	coll2 := session.DB("mydb").C("mycoll2")
+
+	ns := []int{40, 41, 42, 43, 44, 45, 46}
+	for _, n := range ns {
+		err := coll1.Insert(M{"n": n})
+		c.Assert(err, IsNil)
+	}
+
+	// Release master so we can grab a slave again.
+	session.Refresh()
+
+	// Wait until synchronization is done.
+	for {
+		n, err := coll1.Count()
+		c.Assert(err, IsNil)
+		if n == len(ns) {
+			break
+		}
+	}
+
+	iter := coll1.Find(nil).Batch(2).Iter()
+	i := 0
+	m := M{}
+	for iter.Next(&m) {
+		i++
+		if i > 3 {
+			err := coll2.Insert(M{"n": 47 + i})
+			c.Assert(err, IsNil)
+		}
+	}
+	c.Assert(i, Equals, len(ns))
+}
+
+func (s *S) TestSetModeEventual(c *C) {
+	// Must necessarily connect to a slave, otherwise the
+	// master connection will be available first.
+	session, err := mgo.Dial("localhost:40012")
+	c.Assert(err, IsNil)
+	defer session.Close()
+
+	session.SetMode(mgo.Eventual, false)
+
+	c.Assert(session.Mode(), Equals, mgo.Eventual)
+
+	result := M{}
+	err = session.Run("ismaster", &result)
+	c.Assert(err, IsNil)