kressnick25 · kressnick25 · Dec 8, 2024 · Dec 8, 2024 · Dec 8, 2024 · Dec 8, 2024
diff --git a/Makefile b/Makefile
@@ -13,8 +13,9 @@ help:
 	echo
 	echo "Targets run by default are: `sed -n 's/^all: //p' ./Makefile | sed -e 's/ /, /g' | sed -e 's/\(.*\), /\1, and /'`"
 
+
 ## build: Builds a custom 'k6' with the local extension. 
-build:
+build: xk6-config
 	xk6 build --with $(shell go list -m)=.
 
 ## linter-config: Checks if the linter config exists, if not, downloads it from the main k6 repository.
@@ -25,6 +26,10 @@ linter-config:
 check-linter-version:
 	(golangci-lint version | grep "version $(shell head -n 1 .golangci.yml | tr -d '\# ')") || echo "Your installation of golangci-lint is different from the one that is specified in k6's linter config (there it's $(shell head -n 1 .golangci.yml | tr -d '\# ')). Results could be different in the CI."
 
+## xk6-config: checks that xk6 is installed
+xk6-config:
+	command -v xk6 2>&1 > /dev/null || $ go install go.k6.io/xk6/cmd/xk6@latest
+
 ## test: Executes any tests.
 test:
 	go test -timeout 60s ./...

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
-# k6 LDAP Extension
+# xk6-ldap
 
-This is a [k6](https://k6.io) extension that enables LDAP operations within k6 test scripts. It provides a wrapper around the `ldap.v3` package, allowing you to perform LDAP operations such as binding, searching, adding, and deleting entries during load testing.
+A [k6](https://k6.io) extension that enables LDAP operations within k6 scripts. It is mostly a wrapper around the golang `ldap.v3` package.
 
 ## Features
 
@@ -15,6 +15,7 @@ Utils
 
 ### Not implemented (yet)
 - LDAP Modify
+- operation controls
 
 ## Installation
 
@@ -31,25 +32,27 @@ xk6 build --with github.com/kressnick25/xk6-ldap
 ```javascript
 import ldap from 'k6/x/ldap';
 
+// Create LDAP connection using an LDAPURL
+// The connection will be established on the first command call.
+const conn = ldap.dialURL('ldaps://your-ldap-server:636');
+
 export default function () {
-  // Create LDAP connection
-  // Note that if you do not want to create a connection per VU, 
-  // move this to the init context
-  const conn = ldap.dialURL('ldap://your-ldap-server:389');
 
   try {
     // Bind to LDAP server
     conn.bind('cn=admin,dc=example,dc=com', 'admin_password');
 
     // Perform a search
-    const searchRequest = ldap.newSearchRequest(
-      'dc=example,dc=com',      // Base DN
-      'WholeSubtree',           // Scope
-      0,                        // Size Limit (0 for no limit)
-      0,                        // Time Limit (0 for no limit)
-      '(objectClass=person)',   // Filter
-      ['cn', 'mail']           // Attributes to retrieve
-    );
+    const searchRequest = {
+        filter: '(objectClass=person)', // Search Filter
+        baseDn: 'dc=example,dc=org', // Base DN
+        attributes: ['cn', 'mail'], // [] for all attributes
+        scope: 'WholeSubtree', // options: BaseObject, SingleLevel, WholeSubtree
+        sizeLimit: 0, // 0 for no limit
+        timeLimit: 0, // (seconds) 0 for not limit
+        derefAliases: 0,
+        typesOnly: false
+    }
 
     const result = conn.search(searchRequest);
     console.log(result.entries);
@@ -62,52 +65,86 @@ export default function () {
 
 See also `examples/example.js`
 
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is open-source. Please ensure you check the license terms before using it.
+
+## See Also
+
+- [k6 Documentation](https://k6.io/docs/)
+- [LDAP v3 Package Documentation](https://pkg.go.dev/gopkg.in/ldap.v3)
+
+
 ## API Reference
 
-### Ldap
+### Module Import
+```javascript
+import ldap from 'k6/x/ldap'
+```
 
-#### `dialURL(addr: string): Conn`
-Establishes a new connection to an LDAP server using the provided URL.
+### LDAP Module Methods
 
-#### `escapeFilter(filter: string): string`
-Escapes special characters in LDAP filter strings.
+#### dialURL(address: string)
+Establishes a connection to an LDAP server.
 
-#### `newAddRequest(dn: string): AddRequest`
-Creates a new request to add an entry to the LDAP directory.
+**Parameters:**
+- `address` (string): LDAP URL in the format `ldap://host:port`
 
-#### `newDelRequest(dn: string): DelRequest`
-Creates a new request to delete an entry from the LDAP directory.
+**Returns:**
+- Connection object
 
-#### `newSearchRequest(baseDn: string, scope: "BaseObject" | "SingleLevel" | "WholeSubtree", sizeLimit: number, timeLimit: number, filter: string, attributes: string[]): SearchRequest`
-Creates a new search request with the specified parameters.
+#### escapeFilter(filter: string)
+Escapes special characters in LDAP filter strings to prevent injection.
 
-### Conn
+**Parameters:**
+- `filter` (string): LDAP filter string to escape
 
-#### `add(addRequest: AddRequest): void`
-Adds a new entry to the LDAP directory.
+**Returns:**
+- Escaped filter string
 
-#### `del(delRequest: DelRequest): void`
-Deletes an entry from the LDAP directory.
+### Connection Methods
 
-#### `bind(username: string, password: string): void`
-Authenticates with the LDAP server.
+#### bind(username: string, password: string)
+Authenticates the connection with the LDAP server.
 
-#### `search(searchRequest: SearchRequest): SearchResult`
-Performs a search operation. Returns a SearchResult containing matched entries.
+**Parameters:**
+- `username` (string): DN of the user to authenticate as
+- `password` (string): Password for authentication
 
-#### `close(): void`
-Closes the LDAP connection.
+#### search(options: object)
+Performs an LDAP search operation.
 
-## Contributing
+**Parameters:**
+- `options` (object):
+  - `filter` (string, optional): LDAP search filter. Default: "*"
+  - `baseDn` (string, optional): Base DN for search. Default: ""
+  - `attributes` (string[], optional): Attributes to return. Default: []
+  - `scope` (string, optional): Search scope. Default: "WholeSubtree"
+    - Valid values: "BaseObject", "SingleLevel", "WholeSubtree"
+  - `sizeLimit` (number, optional): Maximum entries to return. Default: 0 (unlimited)
+  - `timeLimit` (number, optional): Search time limit in seconds. Default: 0 (unlimited)
+  - `derefAliases` (number, optional): Alias dereferencing option. Default: 0
+  - `typesOnly` (boolean, optional): Return attribute names only. Default: false
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+**Returns:**
+- Search result object containing matching entries
 
-## License
+#### add(dn: string, attributes: string)
+Adds a new entry to the LDAP directory.
 
-This project is open-source. Please ensure you check the license terms before using it.
+**Parameters:**
+- `dn` (string): Distinguished Name for the new entry
+- `attributes` (object): Map of attribute names to arrays of values
 
-## See Also
+#### del(dn: string)
+Deletes an entry from the LDAP directory.
 
-- [k6 Documentation](https://k6.io/docs/)
-- [LDAP v3 Package Documentation](https://pkg.go.dev/gopkg.in/ldap.v3)
+**Parameters:**
+- `dn` (string): Distinguished Name of the entry to delete
 
+#### close()
+Closes the LDAP connection and releases resources.
diff --git a/examples/example.js b/examples/example.js
@@ -1,3 +1,4 @@
+import { check } from 'k6'
 import ldap from 'k6/x/ldap'
 
 
@@ -13,31 +14,43 @@ console.log(`Binding to LDAP with DN: ${bindDn}`)
 ldapConn.bind(bindDn, bindPassword)
 
 export default function () {
-    let filter = '(cn=*)'
-    let baseDn = 'dc=example,dc=org'
-    let attributes = ['cn', 'sn', 'objectClass'] // [] for all attributes
-    let scope = 'WholeSubtree' // options: BaseObject, SingleLevel, WholeSubtree
-    let sizeLimit = 0 // 0 for unlimited
-    let timeLimit = 0 // (seconds). 0 for unlimited
-
-    let searchReq = ldap.newSearchRequest(baseDn, scope, sizeLimit, timeLimit, filter, attributes) 
+    let searchReq = {
+        filter: '(cn=*)',
+        baseDn: 'dc=example,dc=org',
+        attributes: ['cn', 'sn', 'objectClass'], // [] for all attributes
+        scope: 'WholeSubtree', // options: BaseObject, SingleLevel, WholeSubtree
+        sizeLimit: 0, // 0 for unlimited
+        timeLimit: 0, // (seconds). 0 for unlimited
+        derefAliases: 0,
+        typesOnly: false
+    }
 
     let result = ldapConn.search(searchReq)
     console.log(`Search found ${result.entries.length} results`)
-
-    let addRequest = ldap.newAddRequest('cn=test,dc=example,dc=org')
-    addRequest.attribute('sn', ['Smith'])
-    addRequest.attribute('objectClass', ['inetOrgPerson'])
+    check(result.entries, {
+        'expected results': (r) => r.length === 3
+    })
+
+    let addAttributes = {
+        'sn': ['Smith'],
+        'objectClass': ['inetOrgPerson']
+    }
     console.log('Running Add request')
-    ldapConn.add(addRequest)
+    ldapConn.add('cn=test,dc=example,dc=org', addAttributes)
 
 
-    result = ldapConn.search(searchReq)
+    // use default search attributes
+    result = ldapConn.search({
+        filter: '(cn=*)',
+        baseDn: 'dc=example,dc=org'
+    })
     console.log(`Search found ${result.entries.length} results`)
-
-    let delRequest = ldap.newDelRequest('cn=test,dc=example,dc=org')
+    check(result.entries, {
+        'expected results': (r) => r.length === 4
+    })
+
     console.log('Running Delete request')
-    ldapConn.del(addRequest)
+    ldapConn.del('cn=test,dc=example,dc=org')
 
 }