From 622b7486f7a26baf255c8be410d8a19d11fd5bd9 Mon Sep 17 00:00:00 2001 From: Patrick Mooney Date: Fri, 16 Oct 2015 00:25:49 -0500 Subject: [PATCH] First steps toward updating the docs --- Makefile | 12 +- deps/restdown | 2 +- docs/branding/footer.html.in | 80 +++---- docs/branding/header.html.in | 75 +++---- docs/branding/media/css/restdown.css | 325 +++++++++++++++++++++++++++ docs/branding/media/img/logo.svg | 1 + docs/client.md | 66 ++++-- docs/dn.md | 33 ++- docs/errors.md | 6 +- docs/examples.md | 4 - docs/filters.md | 17 +- docs/guide.md | 27 ++- docs/index.md | 32 +-- docs/server.md | 26 +-- tools/mk/Makefile.deps | 2 +- tools/mk/Makefile.targ | 14 +- 16 files changed, 514 insertions(+), 208 deletions(-) create mode 100644 docs/branding/media/css/restdown.css create mode 100644 docs/branding/media/img/logo.svg diff --git a/Makefile b/Makefile index 453525d..9175da9 100644 --- a/Makefile +++ b/Makefile @@ -23,16 +23,8 @@ TAP := ./node_modules/.bin/tap # # Files # -DOC_FILES = client.md \ - dn.md \ - errors.md \ - examples.md \ - filters.md \ - guide.md \ - index.md \ - persistent_search.md \ - server.md - +DOC_FILES := $(shell find docs -name '*.md' -printf '%f\n') +RESTDOWN_FLAGS := -b docs/branding/ JS_FILES := $(shell find lib test -name '*.js') $(shell find bin -name 'ldapjs-*') JSL_CONF_NODE = tools/jsl.node.conf JSL_FILES_NODE = $(JS_FILES) diff --git a/deps/restdown b/deps/restdown index 14131f6..34a843c 160000 --- a/deps/restdown +++ b/deps/restdown @@ -1 +1 @@ -Subproject commit 14131f6b33bf45a04b4c66e388d0ce1f3e5b55ef +Subproject commit 34a843cfce0ff988bf5073706882722a61036786 diff --git a/docs/branding/footer.html.in b/docs/branding/footer.html.in index ee7d55c..5e4f33e 100644 --- a/docs/branding/footer.html.in +++ b/docs/branding/footer.html.in @@ -1,52 +1,46 @@ - - - diff --git a/docs/branding/header.html.in b/docs/branding/header.html.in index 32c1f85..f81d514 100644 --- a/docs/branding/header.html.in +++ b/docs/branding/header.html.in @@ -1,57 +1,32 @@ - %(title)s - - - %(doc_style)s - - + %(title)s + + + -
-
-
+ diff --git a/docs/branding/media/css/restdown.css b/docs/branding/media/css/restdown.css new file mode 100644 index 0000000..c5477d6 --- /dev/null +++ b/docs/branding/media/css/restdown.css @@ -0,0 +1,325 @@ + +/* ---- general styles */ + +body { + font: 13px "Lucida Grande", "Lucida Sans Unicode", arial, sans-serif; + line-height: 1.53846; /* 20px */ + color: #4a3f2d; +} + +:focus { + outline: 0; +} + +h1,h2,h3 { + font-weight:normal; +} + +h3{ + margin-bottom:0; +} + +ul, li { + margin:0px; + padding:0px; +} + +ul { + margin-left:40px; +} + +ul > li { + list-style:disc; + list-style-position:inside; + margin:10px 0px; +} + +hr { + border:none; + width:98%; + margin-left:-10px; + border-top:1px solid #CCCCCC; + border-bottom:1px solid #FFFFFF; +} + +code, +pre { + border:1px solid #CCCCCC; + background:#F2F0EE; + -webkit-border-radius:2px; + -moz-border-radius:2px; + border-radius:2px; + white-space:pre-wrap; +} +code { + padding: 0 0.2em; +} +pre { + margin: 1em 0; + padding: .75em; + overflow: auto; + padding:10px 1.2em; + margin-top:0; + margin-bottom:20px; +} +pre code { + border: medium none; + padding: 0; +} +a code { + text-decoration: underline; +} + +a { + color:#FD6512; + text-decoration:none; +} + +h4 { + font-size: 85%; + margin: 0; + padding: 0; + line-height: 1em; + display: inline; +} + + + +/* ---- custom classes */ + +pre.shell, +pre.shell code { + background:#444; + color:#fff; + border-width:0px; +} +pre.shell code::before { + content: '$ '; + display: inline; +} + + +/* ---- header and sidebar */ + +#header { + background:#C3BDB3; + background:#1C313C; + height:66px; + left:0px; + position:absolute; + top:0px; + width:100%; + z-index:1; + font-size:0.7em; +} + +#header h1 { + width: 424px; + height: 35px; + display:block; + background: url(../img/logo.svg) no-repeat; + line-height:2.1em; + padding:0; + padding-left:140px; + margin-top:18px; + margin-left:20px; + color:white; + text-transform: uppercase; +} + +#sidebar { + background-color:#EDEBEA; + bottom:0px; + left:0px; + overflow:auto; + padding:20px 0px 0px 15px; + position:absolute; + top:66px; + width:265px; + z-index:1; +} + +#content { + top:64px; + bottom:0px; + right:0px; + left:290px; + padding:20px 30px 400px; + position:absolute; + overflow:auto; + z-index:0; +} + +#sidebar .vertical_divider { + background-color:#FFFFFF; + bottom:0px; + position:absolute; + top:0px; + right:0px; + width:1px; +} + +#sidebar h1 { + font-size:1.2em; + padding:0px; + margin-top:15px; + margin-bottom:3px; +} + +#sidebar ul { + margin:3px 0 10px 0; +} + +#sidebar ul ul { + margin:3px 0 5px 10px; +} + +#sidebar li { + margin:0; + padding:0; + font-size:0.9em; +} + +#sidebar li, +#sidebar li a { + color:#5C5954; + list-style:none; + padding:1px 0px 1px 2px; +} + +#sidebar li span.verb { + color:#aaa; + padding:2px 3px 0px; + width:30px; + display:block; + float:left; + font-size:9px; + font-family:verdana; + -moz-border-radius:3px; + -webkit-border-radius:3px; + margin-left:0px; + margin-right:5px; +} + +#sidebar li.current { + background-repeat: no-repeat; + background-position:right; +} + + +/* ---- intro */ + +.intro { + color:#29231A; + padding: 22px 25px; + background: #EDEBEA; + -webkit-border-radius: 5px; + -moz-border-radius: 5px; + -o-border-radius: 5px; + border-radius: 5px; + margin-bottom:40px; +} +.intro pre.base { + background:#444; + color:#29231A; + color:#fff; + border-color:#fff; + font-size:1.5em; +} +.intro h1 { + color: #1C313C; +} +.intro h3 { + margin: 5px 0px 3px; + font-size: 100%; + font-weight: bold; +} +.intro ul { + list-style-type:disc; + padding-left:20px; + margin-left:0; +} +.intro ul li{ + margin:0; +} +.intro p { + padding-left:20px; + margin: 5px 0px 3px; +} + + + +h2 { + overflow: auto; + margin-top: 60px; + border-top: 2px solid #979592; + z-index: 3; +} +h1 + h2 { + margin-top: 0px; +} + +h2.fixed { + position:fixed; + margin-top: 0; + border-top:none; + right:45px; + top:66px; +} + +h2 span { + background: #979592; + float:right; + color:#fff; + margin:0; + margin-left:3px; + padding:0.3em 0.7em; + font-size: 0.55em; + word-spacing: 0.8em; /* separate verb from path */ + color:#fff; +} + + + + +/*---- print media */ + +@media print { + body { background:white; color:black; margin:0; } + #sidebar { + display: none; + } + #content { + position: relative; + padding: 5px; + left: 0px; + top: 0px; + } + h1, h2, h4 { + page-break-after: avoid; + } + pre { + page-break-inside: avoid; + } +} + +/* tables still need cellspacing="0" in the markup */ +table { + border-collapse:collapse; border-spacing:0; + margin: 20px 0; +} +th, +td { + border: solid #aaa; + border-width: 1px 0; + line-height: 23px; + padding: 0 12px; + text-align: left; + vertical-align: text-bottom; +} +th { + border-collapse: separate; +} +tbody tr:nth-child(odd) { + background-color: #f2f0ee; +} diff --git a/docs/branding/media/img/logo.svg b/docs/branding/media/img/logo.svg new file mode 100644 index 0000000..8246eb8 --- /dev/null +++ b/docs/branding/media/img/logo.svg @@ -0,0 +1 @@ + diff --git a/docs/client.md b/docs/client.md index 9917e72..75ef783 100644 --- a/docs/client.md +++ b/docs/client.md @@ -1,15 +1,12 @@ --- title: Client API | ldapjs -markdown2extras: wiki-tables -logo-color: green -logo-font-family: google:Aldrich, Verdana, sans-serif -header-font-family: google:Aldrich, Verdana, sans-serif +markdown2extras: tables --- # ldapjs Client API This document covers the ldapjs client API and assumes that you are familiar -with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first. +with LDAP. If you're not, read the [guide](guide.html) first. # Create a client @@ -25,18 +22,22 @@ that this will not use the LDAP TLS extended operation, but literally an SSL connection to port 636, as in LDAP v2). The full set of options to create a client is: -||url|| a valid LDAP url.|| -||socketPath|| If you're running an LDAP server over a Unix Domain Socket, use this.|| -||log|| You can optionally pass in a bunyan instance the client will use to acquire a logger. The client logs all messages at the `trace` level.|| -||timeout||How long the client should let operations live for before timing out. Default is Infinity.|| -||connectTimeout||How long the client should wait before timing out on TCP connections. Default is up to the OS.|| -||tlsOptions||Additional [options](http://nodejs.org/api/tls.html#tls_tls_connect_port_host_options_callback) passed to the TLS connection layer when connecting via `ldaps://`|| - +|Attribute |Description | +|---------------|-----------------------------------------------------------| +|url |A valid LDAP URL (proto/host/port only) | +|socketPath |Socket path if using AF\_UNIX sockets | +|log |Bunyan logger instance (Default: built-in instance) | +|timeout |How long the client should let operations live for before timing out (Default: Infinity)| +|connectTimeout |How long the client should wait before timing out on TCP connections (Default: OS default)| +|tlsOptions |Additional options passed to the TLS connection layer when connecting via `ldaps://` (See: The TLS docs for node.js)| +|idleTimeout |Seconds after last activity before client emits idle event| +|strictDN |Force strict DN parsing for client methods (Default is true)| ## Connection management As LDAP is a stateful protocol (as opposed to HTTP), having connections torn -down from underneath you is difficult to deal with. +down from underneath you is can be difficult to deal with. Several mechanisms +have been provided to mitigate this trouble. ## Common patterns @@ -49,8 +50,11 @@ Almost every operation has the callback form of `function(err, res)` where err will be an instance of an `LDAPError` (you can use `instanceof` to switch). You probably won't need to check the `res` parameter, but it's there if you do. + + + # bind -`bind(dn, password, controls,callback)` +`bind(dn, password, controls, callback)` Performs a bind operation against the LDAP server. @@ -166,7 +170,7 @@ server. A couple points with this client API: * There is no ability to set "keep old dn." It's always going to flag the old dn to be purged. -* The client code will automagically figure out if the request is a "new +* The client code will automatically figure out if the request is a "new superior" request ("new superior" means move to a different part of the tree, as opposed to just renaming the leaf). @@ -192,12 +196,14 @@ Like every other operation, `base` is a DN string. Options can be a string representing a valid LDAP filter or an object containing the following fields: -||scope||One of `base`, `one`, or `sub`. Defaults to `base`.|| -||filter||A string version of an LDAP filter (see below), or a programatically constructed `Filter` object. Defaults to `(objectclass=*)`.|| -||attributes||attributes to select and return (if these are set, the server will return *only* these attributes). Defaults to the empty set, which means all attributes. You can provide a string if you want a single attribute or an array of string for one or many.|| -||attrsOnly||boolean on whether you want the server to only return the names of the attributes, and not their values. Borderline useless. Defaults to false.|| -||sizeLimit||the maximum number of entries to return. Defaults to 0 (unlimited).|| -||timeLimit||the maximum amount of time the server should take in responding, in seconds. Defaults to 10. Lots of servers will ignore this.|| +|Attribute |Description | +|-----------|---------------------------------------------------| +|scope |One of `base`, `one`, or `sub`. Defaults to `base`.| +|filter |A string version of an LDAP filter (see below), or a programatically constructed `Filter` object. Defaults to `(objectclass=*)`.| +|attributes |attributes to select and return (if these are set, the server will return *only* these attributes). Defaults to the empty set, which means all attributes. You can provide a string if you want a single attribute or an array of string for one or many.| +|attrsOnly |boolean on whether you want the server to only return the names of the attributes, and not their values. Borderline useless. Defaults to false.| +|sizeLimit |the maximum number of entries to return. Defaults to 0 (unlimited).| +|timeLimit |the maximum amount of time the server should take in responding, in seconds. Defaults to 10. Lots of servers will ignore this.| Responses from the `search` method are an `EventEmitter` where you will get a notification for each `searchEntry` that comes back from the server. You will @@ -271,6 +277,24 @@ The `not` character is represented as a `!`, the `or` as a single pipe `|`. It gets a little bit complicated, but it's actually quite powerful, and lets you find almost anything you're looking for. +# starttls +`starttls(options, controls, callback)` + +Attempt to secure existing LDAP connection via STARTTLS. + +Example: + + var opts = { + ca: [fs.readFileSync('mycacert.pem')] + }; + + client.starttls(opts, function(err, res) { + assert.ifError(err); + + // Client communication now TLS protected + }); + + # unbind `unbind(callback)` diff --git a/docs/dn.md b/docs/dn.md index ba311ac..de1463e 100644 --- a/docs/dn.md +++ b/docs/dn.md @@ -1,15 +1,11 @@ --- title: DN API | ldapjs -markdown2extras: wiki-tables -logo-color: green -logo-font-family: google:Aldrich, Verdana, sans-serif -header-font-family: google:Aldrich, Verdana, sans-serif --- # ldapjs DN API This document covers the ldapjs DN API and assumes that you are familiar -with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first. +with LDAP. If you're not, read the [guide](guide.html) first. DNs are LDAP distinguished names, and are composed of a set of RDNs (relative distinguished names). [RFC2253](http://www.ietf.org/rfc/rfc2253.txt) has the @@ -81,6 +77,33 @@ argument. `dn` can be a string or a DN. Returns a DN object that is the direct parent of `this`. If there is no parent this can return `null` (e.g. `parseDN('o=example').parent()` will return null). + +## format(options) + +Convert a DN object to string according to specified formatting options. These +options are divided into two types. Preservation Options use data recorded +during parsing to preserve details of the original DN. Modification options +alter string formatting defaults. Preservation options _always_ take +precedence over Modification Options. + +Preservation Options: + + - `keepOrder`: Order of multi-value RDNs. + - `keepQuote`: RDN values which were quoted will remain so. + - `keepSpace`: Leading/trailing spaces will be output. + - `keepCase`: Parsed attribute name will be output instead of lowercased version. + +Modification Options: + +- `upperName`: RDN names will be uppercased instead of lowercased. +- `skipSpace`: Disable trailing space after RDN separators + +## setFormat(options) + +Sets the default `options` for string formatting when `toString` is called. +It accepts the same parameters as `format`. + + ## toString() Returns the string representation of `this`. diff --git a/docs/errors.md b/docs/errors.md index 554db56..6c6b5ba 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -1,15 +1,11 @@ --- title: Errors API | ldapjs -markdown2extras: wiki-tables -logo-color: green -logo-font-family: google:Aldrich, Verdana, sans-serif -header-font-family: google:Aldrich, Verdana, sans-serif --- # ldapjs Errors API This document covers the ldapjs errors API and assumes that you are familiar -with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first. +with LDAP. If you're not, read the [guide](guide.html) first. All errors in the ldapjs framework extend from an abstract error type called `LDAPError`. In addition to the properties listed below, all errors will have diff --git a/docs/examples.md b/docs/examples.md index b124fc6..71881ef 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,9 +1,5 @@ --- title: Examples | ldapjs -markdown2extras: wiki-tables -logo-color: green -logo-font-family: google:Aldrich, Verdana, sans-serif -header-font-family: google:Aldrich, Verdana, sans-serif --- # ldapjs Examples diff --git a/docs/filters.md b/docs/filters.md index e4a6e0c..c810dc2 100644 --- a/docs/filters.md +++ b/docs/filters.md @@ -1,15 +1,11 @@ --- title: Filters API | ldapjs -markdown2extras: wiki-tables -logo-color: green -logo-font-family: google:Aldrich, Verdana, sans-serif -header-font-family: google:Aldrich, Verdana, sans-serif --- # ldapjs Filters API This document covers the ldapjs filters API and assumes that you are familiar -with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first. +with LDAP. If you're not, read the [guide](guide.html) first. LDAP search filters are really the backbone of LDAP search operations, and ldapjs tries to get you in "easy" with them if your dataset is small, and also @@ -28,17 +24,6 @@ All Filters in the ldapjs framework extend from `Filter`, which wil have the property `type` available; this will return a string name for the filter, and will be one of: -||equal||an `EqualityFilter`|| -||present||a `PresenceFilter`|| -||substring||a `SubstringFilter`|| -||ge||a `GreaterThanEqualsFilter`|| -||le||a `LessThanEqualsFilter`|| -||and||an `AndFilter`|| -||or||an `OrFilter`|| -||not||a `NotFilter`|| -||approx||an `ApproximateMatchFilter` (quasi-supported in ldapjs)|| -||ext||an `ExtensibleMatchFilter` (not supported in ldapjs)|| - # parseFilter(filterString) Parses an [RFC2254](http://www.ietf.org/rfc/rfc2254.txt) filter string into an diff --git a/docs/guide.md b/docs/guide.md index afd5fff..6fb056c 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,9 +1,6 @@ --- title: LDAP Guide | ldapjs -markdown2extras: wiki-tables -logo-color: green -logo-font-family: google:Aldrich, Verdana, sans-serif -header-font-family: google:Aldrich, Verdana, sans-serif +markdown2extras: tables --- # LDAP Guide @@ -135,7 +132,7 @@ since we haven't added any support in yet, but go ahead and try it anyway: $ ldapsearch -H ldap://localhost:1389 -x -b "o=myhost" objectclass=* Before we go any further, note that the complete code for the server we are -about to build up is on the [examples](http://ldapjs.org/examples.html) page. +about to build up is on the [examples](examples.html) page. ## Bind @@ -237,13 +234,15 @@ for a moment to explain an /etc/passwd record. The sample record above maps to: -||jsmith||user name.|| -||x||historically this contained the password hash, but that's usually in /etc/shadow now, so you get an 'x'.|| -||1001||the unix numeric user id.|| -||1000||the unix numeric group id. (primary).|| -||'Joe Smith,...'||the "gecos," which is a description, and is usually a comma separated list of contact details.|| -||/home/jsmith||the user's home directory.|| -||/bin/sh||the user's shell.|| +|Field |Description | +|-------------------|-----------------------------------| +|jsmith |Username | +|x |Placeholder for password hash | +|1001 |Numeric UID | +|1000 |Numeric Primary GID | +|'Joe Smith,...' |DisplayName | +|/home/jsmith |Home directory | +|/bin/sh |Shell | Let's write some handlers to parse that and transform it into an LDAP search record (note, you'll need to add `var fs = require('fs');` at the top of the @@ -629,8 +628,8 @@ And then run the following command: # Where to go from here The complete source code for this example server is available in -[examples](/examples.html). Make sure to read up on the [server](/server.html) -and [client](/client.html) APIs. If you're looking for a "drop in" solution, +[examples](examples.html). Make sure to read up on the [server](server.html) +and [client](client.html) APIs. If you're looking for a "drop in" solution, take a look at [ldapjs-riak](https://github.com/mcavage/node-ldapjs-riak). [Mozilla](https://wiki.mozilla.org/Mozilla_LDAP_SDK_Programmer%27s_Guide/Understanding_LDAP) diff --git a/docs/index.md b/docs/index.md index bd7a0a0..e8c05db 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,6 @@ --- title: ldapjs -markdown2extras: wiki-tables -logo-color: green -logo-font-family: google:Aldrich, Verdana, sans-serif -header-font-family: google:Aldrich, Verdana, sans-serif +markdown2extras: tables ---
@@ -15,7 +12,7 @@ Reimagining LDAP< ldapjs is a pure JavaScript, from-scratch framework for implementing [LDAP](http://tools.ietf.org/html/rfc4510) clients and servers in [Node.js](http://nodejs.org). It is intended for developers used to interacting -with HTTP services in node and [express](http://expressjs.com). +with HTTP services in node and [restify](http://restify.com). var ldap = require('ldapjs'); @@ -57,22 +54,25 @@ that you can build LDAP over anything you want, not just traditional databases. $ npm install ldapjs -If you're new to LDAP, check out the [guide](/guide.html). Otherwise, the +If you're new to LDAP, check out the [guide](guide.html). Otherwise, the API documentation is: -||[server](/server.html)||Reference for implementing LDAP servers.|| -||[client](/client.html)||Reference for implementing LDAP clients.|| -||[dn](/dn.html)||API reference for the DN class.|| -||[filters](/filters.html)||API reference for LDAP search filters.|| -||[errors](/errors.html)||Listing of all ldapjs Error objects.|| -||[examples](/examples.html)||Collection of sample/getting started code.|| + +|Section |Content | +|---------------------------|-------------------------------------------| +|[Server API](server.html) |Reference for implementing LDAP servers. | +|[Client API](client.html) |Reference for implementing LDAP clients. | +|[DN API](dn.html) |API reference for the DN class. | +|[Filter API](filters.html) |API reference for LDAP search filters. | +|[Error API](errors.html) |Listing of all ldapjs Error objects. | +|[Examples](examples.html) |Collection of sample/getting started code. | # More information -||License||[MIT](http://opensource.org/licenses/mit-license.php)|| -||Code||[mcavage/node-ldapjs](https://github.com/mcavage/node-ldapjs)|| -||node.js version||>=0.6|| -||Twitter||[@mcavage](http://twitter.com/mcavage)|| +- License:[MIT](http://opensource.org/licenses/mit-license.php) +- Code: [mcavage/node-ldapjs](https://github.com/mcavage/node-ldapjs) +- node.js version: >=0.8 +- Twitter: [@pfmooney](http://twitter.com/pfmooney) # What's not in the box? diff --git a/docs/server.md b/docs/server.md index 8c77f2d..8d41882 100644 --- a/docs/server.md +++ b/docs/server.md @@ -1,15 +1,12 @@ --- title: Server API | ldapjs markdown2extras: wiki-tables -logo-color: green -logo-font-family: google:Aldrich, Verdana, sans-serif -header-font-family: google:Aldrich, Verdana, sans-serif --- # ldapjs Server API This document covers the ldapjs server API and assumes that you are familiar -with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first. +with LDAP. If you're not, read the [guide](guide.html) first. # Create a server @@ -47,8 +44,7 @@ Emitted when the server closes. ## Listening for requests -The LDAP server API wraps up and mirrors the node -[listen](http://nodejs.org/docs/v0.4.11/api/net.html#server.listen) family of +The LDAP server API wraps up and mirrors the node.js `server.listen` family of APIs. After calling `listen`, the property `url` on the server object itself will be @@ -66,7 +62,7 @@ Example: Begin accepting connections on the specified port and host. If the host is omitted, the server will accept connections directed to any IPv4 address -(INADDR_ANY). +(INADDR\_ANY). This function is asynchronous. The last parameter callback will be called when the server has been bound. @@ -90,7 +86,7 @@ calls invoked on it. Additionally, it must be set non-blocking; try # Routes -The LDAP server API is meant to be the LDAP-equivalent of the express/sinatra +The LDAP server API is meant to be the LDAP-equivalent of the express/restify paradigm of programming. Essentially every method is of the form `OP(req, res, next)` where OP is one of bind, add, del, etc. You can chain handlers together by calling `next()` and ordering your functions in the @@ -112,8 +108,8 @@ caching, etc. that need to be placed in an object. For example [ldapjs-riak](https://github.com/mcavage/node-ldapjs-riak) is a complete implementation of the LDAP protocol over -[Riak](http://www.basho.com/products_riak_overview.php). Getting an LDAP -server up with riak looks like: +[Riak](https://github.com/basho/riak). Getting an LDAP server up with riak +looks like: var ldap = require('ldapjs'); var ldapRiak = require('ldapjs-riak'); @@ -155,7 +151,7 @@ All request objects have the `dn` getter on it, which is "context-sensitive" and returns the point in the tree that the operation wants to operate on. The LDAP protocol itself sadly doesn't define operations this way, and has a unique name for just about every op. So, ldapjs calls it `dn`. The DN object itself -is documented at [DN](/dn.html). +is documented at [DN](dn.html). All requests have an optional array of `Control` objects. `Control` will have the properties `type` (string), `criticality` (boolean), and optionally, a @@ -175,7 +171,7 @@ identify the request/connection pair in logs (includes the LDAP messageID). All response objects will have an `end` method on them. By default, calling `res.end()` with no arguments will return SUCCESS (0x00) to the client -(with the exception of `compare` which will return COMPARE_TRUE (0x06)). You +(with the exception of `compare` which will return COMPARE\_TRUE (0x06)). You can pass in a status code to the `end()` method to return an alternate status code. @@ -186,8 +182,8 @@ and error message for you. ## Errors ldapjs includes an exception hierarchy that directly corresponds to the RFC list -of error codes. The complete list is documented in [errors](/errors.html). But -the paradigm is something defined like CONSTRAINT_VIOLATION in the RFC would be +of error codes. The complete list is documented in [errors](errors.html). But +the paradigm is something defined like CONSTRAINT\_VIOLATION in the RFC would be `ConstraintViolationError` in ldapjs. Upon calling `next(new LDAPError())`, ldapjs will _stop_ calling your handler chain. For example: @@ -330,7 +326,7 @@ Whether to return only the names of attributes, and not the values. Defaults to ### filter -The [filter](/filters.html) object that the client requested. Notably this has +The [filter](filters.html) object that the client requested. Notably this has a `matches()` method on it that you can leverage. For an example of introspecting a filter, take a look at the ldapjs-riak source. diff --git a/tools/mk/Makefile.deps b/tools/mk/Makefile.deps index 9317daf..eeae27f 100644 --- a/tools/mk/Makefile.deps +++ b/tools/mk/Makefile.deps @@ -40,5 +40,5 @@ $(JSSTYLE_EXEC): | deps/jsstyle/.git # restdown # RESTDOWN_EXEC ?= deps/restdown/bin/restdown -RESTDOWN ?= python2.6 $(RESTDOWN_EXEC) +RESTDOWN ?= python $(RESTDOWN_EXEC) $(RESTDOWN_EXEC): | deps/restdown/.git diff --git a/tools/mk/Makefile.targ b/tools/mk/Makefile.targ index 22c9bef..48d07b4 100644 --- a/tools/mk/Makefile.targ +++ b/tools/mk/Makefile.targ @@ -239,8 +239,8 @@ DOC_MEDIA_FILES_BUILD := $(DOC_MEDIA_FILES:%=$(DOC_BUILD)/media/%) # .PHONY: docs docs: \ - $(DOC_FILES:%.restdown=$(DOC_BUILD)/%.html) \ - $(DOC_FILES:%.restdown=$(DOC_BUILD)/%.json) \ + $(DOC_FILES:%.md=$(DOC_BUILD)/%.html) \ + $(DOC_FILES:%.md=$(DOC_BUILD)/%.json) \ $(DOC_MEDIA_FILES_BUILD) # @@ -248,16 +248,16 @@ docs: \ # files in DOC_BUILD are up to date. # .PRECIOUS: \ - $(DOC_FILES:%.restdown=docs/%.html) \ - $(DOC_FILES:%.restdown=docs/%json) + $(DOC_FILES:%.md=docs/%.html) \ + $(DOC_FILES:%.md=docs/%json) # # We do clean those intermediate files, as well as all of DOC_BUILD. # CLEAN_FILES += \ $(DOC_BUILD) \ - $(DOC_FILES:%.restdown=docs/%.html) \ - $(DOC_FILES:%.restdown=docs/%.json) + $(DOC_FILES:%.md=docs/%.html) \ + $(DOC_FILES:%.md=docs/%.json) # # Before installing the files, we must make sure the directories exist. The | @@ -270,7 +270,7 @@ $(DOC_MEDIA_FILES_BUILD): | $(DOC_MEDIA_DIRS_BUILD) $(DOC_BUILD)/%: docs/% | $(DOC_BUILD) $(CP) $< $@ -docs/%.json docs/%.html: docs/%.restdown | $(DOC_BUILD) $(RESTDOWN_EXEC) +docs/%.json docs/%.html: docs/%.md | $(DOC_BUILD) $(RESTDOWN_EXEC) $(RESTDOWN) $(RESTDOWN_FLAGS) -m $(DOC_BUILD) $< $(DOC_BUILD):