feature: support Unbind requests

Author: jimlambrt

README.md

@@ -143,14 +143,11 @@ func searchHandler(w *gldap.ResponseWriter, r *gldap.Request) {
 * Modify Requests
 * Add Requests
 * Delete Requests
+* Unbind Requests
 
-### Near-term features 
-
-* Unbind Requests 
-  
-### Long-term features
-
-* ???
+### Future features
+At this point, we may wait until issues are opened before planning new features
+given that all the basic LDAP operations are supported. 
 
 <hr>
 

conn.go

@@ -111,7 +111,13 @@ func (c *conn) serveRequests() error {
 		// BusyResponse when the limit is reached.  This limit per conn
 		// should be configurable
 
-		// TODO: stop serving requests when an UnbindRequest is received
+		case r.routeOp == unbindRouteOperation:
+			// support an optional unbind route
+			if c.router.unbindRoute != nil {
+				c.router.unbindRoute.handler()(w, r)
+			}
+			// stop serving requests when UnbindRequest is received
+			return nil
 
 		// If it's a StartTLS request, then we can't dispatch it concurrently,
 		// since the conn needs to complete it's TLS negotiation before handling

message.go

@@ -44,6 +44,7 @@ const (
 	modifyRequestType   requestType = "modify"
 	addRequestType      requestType = "add"
 	deleteRequestType   requestType = "delete"
+	unbindRequestType   requestType = "unbind"
 )
 
 // Message defines a common interface for all messages
@@ -115,6 +116,11 @@ type DeleteMessage struct {
 	Controls []Control
 }
 
+// UnbindMessage is an unbind request message
+type UnbindMessage struct {
+	baseMessage
+}
+
 // newMessage will create a new message from the packet.
 func newMessage(p *packet) (Message, error) {
 	const op = "gldap.NewMessage"
@@ -130,6 +136,12 @@ func newMessage(p *packet) (Message, error) {
 	}
 
 	switch reqType {
+	case unbindRequestType:
+		return &UnbindMessage{
+			baseMessage: baseMessage{
+				id: msgID,
+			},
+		}, nil
 	case bindRequestType:
 		u, pass, controls, err := p.simpleBindParameters()
 		if err != nil {

mux.go

@@ -12,6 +12,7 @@ type Mux struct {
 	mu           sync.Mutex
 	routes       []route
 	defaultRoute route
+	unbindRoute  route
 }
 
 // NewMux creates a new multiplexer.
@@ -44,6 +45,31 @@ func (m *Mux) Bind(bindFn HandlerFunc, opt ...Option) error {
 	return nil
 }
 
+// Unbind will register a handler for unbind requests and override the default
+// unbind handler.  Registering an unbind handler is optional and regardless of
+// whether or not an unbind route is defined the server will stop serving
+// requests for a connection after an unbind request is received.  Options
+// supported: WithLabel
+func (m *Mux) Unbind(bindFn HandlerFunc, opt ...Option) error {
+	const op = "gldap.(Mux).Unbind"
+	if bindFn == nil {
+		return fmt.Errorf("%s: missing HandlerFunc: %w", op, ErrInvalidParameter)
+	}
+	opts := getRouteOpts(opt...)
+
+	r := &unbindRoute{
+		baseRoute: &baseRoute{
+			h:       bindFn,
+			routeOp: bindRouteOperation,
+			label:   opts.withLabel,
+		},
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.unbindRoute = r
+	return nil
+}
+
 // Search will register a handler for search requests.
 // Options supported: WithLabel, WithBaseDN, WithScope
 func (m *Mux) Search(searchFn HandlerFunc, opt ...Option) error {

mux_test.go

@@ -146,3 +146,44 @@ func TestMux_Delete(t *testing.T) {
 		})
 	}
 }
+
+func TestMux_Unbind(t *testing.T) {
+	tests := []struct {
+		name            string
+		mux             *Mux
+		fn              HandlerFunc
+		wantErr         bool
+		wantErrIs       error
+		wantErrContains string
+	}{
+		{
+			name:            "missing-fn",
+			mux:             func() *Mux { m, err := NewMux(); require.NoError(t, err); return m }(),
+			wantErr:         true,
+			wantErrIs:       ErrInvalidParameter,
+			wantErrContains: "missing HandlerFunc",
+		},
+		{
+			name: "valid",
+			mux:  func() *Mux { m, err := NewMux(); require.NoError(t, err); return m }(),
+			fn:   func(*ResponseWriter, *Request) {},
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			assert, require := assert.New(t), require.New(t)
+			err := tc.mux.Unbind(tc.fn)
+			if tc.wantErr {
+				require.Error(err)
+				if tc.wantErrIs != nil {
+					assert.ErrorIs(err, tc.wantErrIs)
+				}
+				if tc.wantErrContains != "" {
+					assert.Contains(err.Error(), tc.wantErrContains)
+				}
+				return
+			}
+			require.NoError(err)
+		})
+	}
+}

packet.go

@@ -129,6 +129,8 @@ func (p *packet) requestType() (requestType, error) {
 		return addRequestType, nil
 	case ApplicationDelRequest:
 		return deleteRequestType, nil
+	case ApplicationUnbindRequest:
+		return unbindRequestType, nil
 	default:
 		return unknownRequestType, fmt.Errorf("%s: unhandled request type %d: %w", op, requestPacket.Tag, ErrInternal)
 	}
@@ -537,8 +539,8 @@ func (p *packet) assertApplicationRequest() error {
 	}
 	switch chkPacket.TagType {
 	case ber.TypePrimitive:
-		if chkPacket.Tag != ApplicationDelRequest {
-			return fmt.Errorf("%s: incorrect type, primitive %q must be a delete request %q, but got %q", op, ber.TypePrimitive, ApplicationDelRequest, chkPacket.Tag)
+		if chkPacket.Tag != ApplicationDelRequest && chkPacket.Tag != ApplicationUnbindRequest {
+			return fmt.Errorf("%s: incorrect type, primitive %q must be a delete request %q or an unbind request %q, but got %q", op, ber.TypePrimitive, ApplicationDelRequest, ApplicationUnbindRequest, chkPacket.Tag)
 		}
 	case ber.TypeConstructed:
 	default:

request.go

@@ -61,6 +61,8 @@ func newRequest(id int, c *conn, p *packet) (*Request, error) {
 		routeOp = addRouteOperation
 	case *DeleteMessage:
 		routeOp = deleteRouteOperation
+	case *UnbindMessage:
+		routeOp = unbindRouteOperation
 	default:
 		// this should be unreachable, since newMessage defaults to returning an
 		// *ExtendedOperationMessage
@@ -256,6 +258,17 @@ func (r *Request) GetDeleteMessage() (*DeleteMessage, error) {
 	return m, nil
 }
 
+// GetUnbindMessage retrieves the UnbindMessage from the request, which
+// allows you handle the request based on the message attributes.
+func (r *Request) GetUnbindMessage() (*UnbindMessage, error) {
+	const op = "gldap.(Request).GetUnbindMessage"
+	m, ok := r.message.(*UnbindMessage)
+	if !ok {
+		return nil, fmt.Errorf("%s: %T not an unbind request: %w", op, r.message, ErrInvalidParameter)
+	}
+	return m, nil
+}
+
 func intPtr(i int) *int {
 	return &i
 }

request_test.go

@@ -73,6 +73,19 @@ func Test_newRequest(t *testing.T) {
 				},
 			},
 		},
+		{
+			name:      "valid-unbind",
+			requestID: 1,
+			conn:      &conn{},
+			packet: testUnbindRequestPacket(t,
+				UnbindMessage{
+					baseMessage: baseMessage{id: 1},
+				},
+			),
+			wantMsg: &UnbindMessage{
+				baseMessage: baseMessage{id: 1},
+			},
+		},
 		{
 			name:      "valid-search",
 			requestID: 1,

route.go

@@ -29,6 +29,9 @@ const (
 	// deleteRouteOperation is a route supporting the delete operation
 	deleteRouteOperation routeOperation = "delete"
 
+	// unbindRouteOperation is a route supporting the unbind operation
+	unbindRouteOperation routeOperation = "unbind"
+
 	// defaultRouteOperation is a default route which is used when there are no routes
 	// defined for a particular operation
 	defaultRouteOperation routeOperation = "noRoute"
@@ -73,6 +76,10 @@ type simpleBindRoute struct {
 	authChoice AuthChoice
 }
 
+type unbindRoute struct {
+	*baseRoute
+}
+
 type extendedRoute struct {
 	*baseRoute
 	extendedName ExtendedOperationName

testing.go

@@ -88,6 +88,18 @@ func testSimpleBindRequestPacket(t *testing.T, m SimpleBindMessage) *packet {
 	}
 }
 
+func testUnbindRequestPacket(t *testing.T, m UnbindMessage) *packet {
+	t.Helper()
+
+	envelope := testRequestEnvelope(t, int(m.GetID()))
+	pkt := ber.Encode(ber.ClassApplication, ber.TypeConstructed, ApplicationUnbindRequest, nil, "Unbind Request")
+	envelope.AppendChild(pkt)
+
+	return &packet{
+		Packet: envelope,
+	}
+}
+
 func testModifyRequestPacket(t *testing.T, m ModifyMessage) *packet {
 	t.Helper()
 	envelope := testRequestEnvelope(t, int(m.GetID()))

testing_e2e_test.go

@@ -4,6 +4,7 @@ import (
 	"crypto/tls"
 	"crypto/x509"
 	"fmt"
+	"sync"
 	"testing"
 
 	"github.com/go-ldap/ldap/v3"
@@ -616,3 +617,63 @@ func TestDirectory_DeleteResponse(t *testing.T) {
 		})
 	}
 }
+
+func Test_Start_Unbind(t *testing.T) {
+	t.Parallel()
+	t.Run("unbind", func(t *testing.T) {
+		assert, require := assert.New(t), require.New(t)
+		port := testdirectory.FreePort(t)
+
+		l := hclog.New(&hclog.LoggerOptions{
+			Name:  "simple-bind-logger",
+			Level: hclog.Error,
+		})
+
+		// create a new server
+		s, err := gldap.NewServer(gldap.WithLogger(l), gldap.WithDisablePanicRecovery())
+		require.NoError(err)
+
+		// create a router and add a bind handler
+		r, err := gldap.NewMux()
+		require.NoError(err)
+
+		var got string
+		var wg sync.WaitGroup
+		wg.Add(1)
+		r.Unbind(func(w *gldap.ResponseWriter, req *gldap.Request) {
+			m, err := req.GetUnbindMessage()
+			if err != nil {
+				t.Fatalf("unable to get unbind msg: %s", err.Error())
+			}
+			if m == nil {
+				t.Fatal("unbind msg is nil")
+			}
+			got = "unbind-success"
+			wg.Done()
+		})
+
+		r.Bind(func(w *gldap.ResponseWriter, r *gldap.Request) {
+			resp := r.NewBindResponse(gldap.WithResponseCode(gldap.ResultSuccess))
+			defer func() {
+				_ = w.Write(resp)
+			}()
+		})
+
+		s.Router(r)
+		go s.Run(fmt.Sprintf(":%d", port))
+		defer s.Stop()
+
+		conn, err := ldap.DialURL(fmt.Sprintf("ldap://localhost:%d", port))
+		require.NoError(err)
+		defer conn.Close()
+
+		err = conn.Bind("does not", "matter")
+		require.NoError(err)
+
+		err = conn.Unbind()
+		require.NoError(err)
+
+		wg.Wait()
+		assert.Equal("unbind-success", got)
+	})
+}