box: box.New returns an error instead of panic

Method `box.New` now returns (*Box, error), because avoiding panics
entirely in third-party libraries is ideal, since we can't break
compatibility.

Nonetheless, there is still a way to panic on error, via implemented
`box.MustNew` wrapper.

Part of #448

Author: laines-it

CHANGELOG.md

@@ -11,13 +11,16 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release.
 ### Added
 
 * New types for MessagePack extensions compatible with go-option (#459).
+* Added `box.MustNew` wrapper for `box.New`: panics when `box.New` returns an error (#448).
 
 ### Changed
 
 * Required Go version is `1.24` now (#456).
 
 ### Fixed
 
+* `box.New` returns an error instead of panic (#448).
+
 ## [v2.4.1] - 2025-10-16
 
 This maintenance release marks the end of active development on the `v2`

box/box.go

@@ -1,6 +1,8 @@
 package box
 
 import (
+	"errors"
+
 	"github.com/tarantool/go-tarantool/v3"
 )
 
@@ -11,16 +13,25 @@ type Box struct {
 }
 
 // New returns a new instance of the box structure, which implements the Box interface.
-func New(conn tarantool.Doer) *Box {
+func New(conn tarantool.Doer) (*Box, error) {
 	if conn == nil {
-		// Check if the provided Tarantool connection is nil, and if it is, panic with an error
-		// message. panic early helps to catch and fix nil pointer issues in the code.
-		panic("tarantool connection cannot be nil")
+		return nil, errors.New("tarantool connection cannot be nil")
 	}
 
 	return &Box{
 		conn: conn, // Assigns the provided Tarantool connection.
+	}, nil
+}
+
+// MustNew returns a new instance of the box structure, which implements the Box interface.
+func MustNew(conn tarantool.Doer) *Box {
+	b, err := New(conn)
+	if err != nil {
+		// Check if the provided Tarantool connection is nil, and if it is, panic with an error
+		// message. panic early helps to catch and fix nil pointer issues in the code
+		panic(err)
 	}
+	return b
 }
 
 // Schema returns a new Schema instance, providing access to schema-related operations.

box/box_test.go

@@ -15,8 +15,15 @@ import (
 func TestNew(t *testing.T) {
 	t.Parallel()
 
+	_, err := box.New(nil)
+	require.Error(t, err)
+}
+
+func TestMustNew(t *testing.T) {
+	t.Parallel()
+
 	// Create a box instance with a nil connection. This should lead to a panic.
-	require.Panics(t, func() { box.New(nil) })
+	require.Panics(t, func() { box.MustNew(nil) })
 }
 
 func TestMocked_BoxInfo(t *testing.T) {
@@ -37,7 +44,8 @@ func TestMocked_BoxInfo(t *testing.T) {
 	mock := test_helpers.NewMockDoer(t,
 		test_helpers.NewMockResponse(t, data),
 	)
-	b := box.New(&mock)
+	b, err := box.New(&mock)
+	require.NoError(t, err)
 
 	info, err := b.Info()
 	require.NoError(t, err)
@@ -57,7 +65,8 @@ func TestMocked_BoxSchemaUserInfo(t *testing.T) {
 	mock := test_helpers.NewMockDoer(t,
 		test_helpers.NewMockResponse(t, data),
 	)
-	b := box.New(&mock)
+	b, err := box.New(&mock)
+	require.NoError(t, err)
 
 	privs, err := b.Schema().User().Info(context.Background(), "username")
 	require.NoError(t, err)
@@ -82,8 +91,9 @@ func TestMocked_BoxSessionSu(t *testing.T) {
 		test_helpers.NewMockResponse(t, []interface{}{}),
 		errors.New("user not found or supplied credentials are invalid"),
 	)
-	b := box.New(&mock)
+	b, err := box.New(&mock)
+	require.NoError(t, err)
 
-	err := b.Session().Su(context.Background(), "admin")
+	err = b.Session().Su(context.Background(), "admin")
 	require.NoError(t, err)
 }

box/example_test.go

@@ -45,7 +45,10 @@ func ExampleBox_Info() {
 
 	// Or use simple Box implementation.
 
-	b := box.New(client)
+	b, err := box.New(client)
+	if err != nil {
+		log.Fatalf("Failed get box info: %s", err)
+	}
 
 	info, err := b.Info()
 	if err != nil {
@@ -88,7 +91,11 @@ func ExampleSchemaUser_Exists() {
 	}
 
 	// Or use simple User implementation.
-	b := box.New(client)
+	b, err := box.New(client)
+	if err != nil {
+		log.Fatalf("Failed get box info: %s", err)
+	}
+
 	exists, err := b.Schema().User().Exists(ctx, "user")
 	if err != nil {
 		log.Fatalf("Failed get box schema user exists with error: %s", err)
@@ -120,7 +127,11 @@ func ExampleSchemaUser_Create() {
 	}
 
 	// Create SchemaUser.
-	schemaUser := box.New(client).Schema().User()
+	b, err := box.New(client)
+	if err != nil {
+		log.Fatalf("Failed to connect: %s", err)
+	}
+	schemaUser := b.Schema().User()
 
 	// Create a new user.
 	username := "new_user"
@@ -153,7 +164,11 @@ func ExampleSchemaUser_Drop() {
 	}
 
 	// Create SchemaUser.
-	schemaUser := box.New(client).Schema().User()
+	b, err := box.New(client)
+	if err != nil {
+		log.Fatalf("Failed to connect: %s", err)
+	}
+	schemaUser := b.Schema().User()
 
 	// Drop an existing user.
 	username := "new_user"
@@ -192,7 +207,11 @@ func ExampleSchemaUser_Password() {
 	}
 
 	// Create SchemaUser.
-	schemaUser := box.New(client).Schema().User()
+	b, err := box.New(client)
+	if err != nil {
+		log.Fatalf("Failed to connect: %s", err)
+	}
+	schemaUser := b.Schema().User()
 
 	// Get the password hash.
 	password := "my-password"
@@ -221,7 +240,11 @@ func ExampleSchemaUser_Info() {
 	}
 
 	// Create SchemaUser.
-	schemaUser := box.New(client).Schema().User()
+	b, err := box.New(client)
+	if err != nil {
+		log.Fatalf("Failed to connect: %s", err)
+	}
+	schemaUser := b.Schema().User()
 
 	info, err := schemaUser.Info(ctx, "test")
 	if err != nil {

box/session_test.go

@@ -10,7 +10,8 @@ import (
 )
 
 func TestBox_Session(t *testing.T) {
-	b := box.New(th.Ptr(th.NewMockDoer(t)))
+	b, err := box.New(th.Ptr(th.NewMockDoer(t)))
+	require.NoError(t, err)
 	require.NotNil(t, b.Session())
 }