First steps toward updating the docs

This commit is contained in:
Patrick Mooney 2015-10-16 00:25:49 -05:00
parent 9ec1e9022d
commit 622b7486f7
16 changed files with 514 additions and 208 deletions

View File

@ -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)

2
deps/restdown vendored

@ -1 +1 @@
Subproject commit 14131f6b33bf45a04b4c66e388d0ce1f3e5b55ef
Subproject commit 34a843cfce0ff988bf5073706882722a61036786

View File

@ -1,52 +1,46 @@
<div id="footer">
<p class='copy'>Copyright &copy; 2011 <a href="https://github.com/mcavage">Mark Cavage</a></p>
</div>
</div> <!-- end of #main -->
</div> <!-- end of #wrapper -->
<script type="text/javascript" charset="utf-8">
$(function () {
$("#toc").click(function(event) {
// This to ensure clicks in the #toc don't make it up to the
// button handler.
event.stopPropagation();
});
$("#toc a").click(function(event) {
$("#tocbutton").click();
})
$("#tocbutton").click(function(event) {
var target = $("#toc");
if (target.css("display") !== "block") {
$("body").bind("click.tocCloser", function(event) {
$("#tocbutton").click();
event.stopPropagation();
});
$(function() {
var headerHeight = $("#header").height();
var offsets = [];
var current = -1;
function endpoint(scrollDistance) {
if (scrollDistance < offsets[0]) {
return -1;
} else {
$("body").unbind("click.tocCloser");
for (var id = offsets.length; id > 0; id--) {
if (scrollDistance > offsets[id - 1]) {
return id - 1;
break;
}
}
}
target.slideToggle(100);
event.stopPropagation();
}
$("h2").each(function(i) {
offsets.push($(this).offset().top - headerHeight)
});
$("#api").click(function(event) {
// This to ensure clicks in the #api don't make it up to the
// button handler.
event.stopPropagation();
});
$("#api a").click(function(event) {
$("#apibutton").click();
})
$("#apibutton").click(function(event) {
var target = $("#api");
if (target.css("display") !== "block") {
$("body").bind("click.apiCloser", function(event) {
$("#apibutton").click();
event.stopPropagation();
});
} else {
$("body").unbind("click.apiCloser");
$("#content").append('<h2 class="fixed" style="display: none"><span>&nbsp;</span></h2>');
var fixed_h2 = $("h2.fixed");
var fixed_span = $("h2.fixed span");
$("#content").scroll(function() {
var scrollDistance = $("#content").attr('scrollTop');
var now = endpoint(scrollDistance);
if (now !== current) {
$("#sidebar li").removeClass("current");
current = now;
if (current < 0) {
fixed_h2.hide();
} else if (current >= 0) {
var heading = $($("h2 span")[current]).text();
$("#sidebar a[href|=#" + heading.replace(' ', '-') + "]").parent().addClass("current");
fixed_span.text(heading);
fixed_h2.show();
}
}
target.slideToggle(100);
event.stopPropagation();
});
});
</script>

View File

@ -1,57 +1,32 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>%(title)s</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="%(mediaroot)s/css/style.css">
%(doc_style)s
<script type="text/javascript" src="media/js/jquery-1.4.2.min.js"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-25326304-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<title>%(title)s</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="%(mediaroot)s/css/restdown.css">
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
</head>
<body>
<div id="wrapper">
<div id="main">
<div id="fadeout"></div>
<div id="header">
<span id="logo">
<a id="homelink" href="http://ldapjs.org">ldapjs</a>
</span>
<a class="navbutton" href="guide.html">Guide</a>
<span id="apibox">
<span id="apibutton" class="navbutton">API</span>
<div id="api" class="popup" style="display: none">
<ul>
<li><div><a href="server.html">server</a></div></li>
<li><div><a href="client.html">client</a></div></li>
<li><div><a href="dn.html">dn</a></div></li>
<li><div><a href="filters.html">filters</a></div></li>
<li><div><a href="errors.html">errors</a></div></li>
<li><div><a href="examples.html">examples</a></div></li>
</ul>
</div>
</span>
<span id="tocbox">
<span id="tocbutton" class="navbutton">Page Contents</span>
<div id="toc" class="popup" style="display: none">
%(toc_html)s
</div>
</span>
<a id="githubfork" href="http://github.com/mcavage/node-ldapjs">
<img src="https://a248.e.akamai.net/assets.github.com/img/abad93f42020b733148435e2cd92ce15c542d320/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677265656e5f3030373230302e706e67"
alt="Fork me on GitHub">
</a>
<h1>%(title)s Documentation</h1>
</div>
<div id="sidebar">
<div>Sections</div>
<span>
<ul>
<li><div><a href="index.html">Home</a></div></li>
<li><div><a href="guide.html">Guide</a></div></li>
<li><div><a href="examples.html">Examples</a></div></li>
<li><div><a href="client.html">Client API</a></div></li>
<li><div><a href="server.html">Server API</a></div></li>
<li><div><a href="dn.html">DN API</a></div></li>
<li><div><a href="filters.html">Filters API</a></div></li>
<li><div><a href="errors.html">Error API</a></div></li>
</ul>
</span>
<div>Contents</div>
</span>
%(toc_html)s
</div>

View File

@ -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;
}

View File

@ -0,0 +1 @@
<svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="125" height="34.1" viewBox="0 0 146.25 39.96"><defs><path d="M-2.21-3.96h150v45.93h-150z"/><clipPath><use xlink:href="#a" overflow="visible"/></clipPath><clipPath><use xlink:href="#c-4" overflow="visible"/></clipPath></defs><clipPath><use xlink:href="#a" overflow="visible"/></clipPath><g clip-path="url(#b-8)" fill="#f60"><defs><path d="m-2.21-3.96 150 0 0 45.93-150 0z"/></defs><clipPath><use xlink:href="#c-4" overflow="visible" x="0" y="0" width="100" height="100"/></clipPath><path d="m15.74 31.29c8.61 0 15.6-6.98 15.6-15.59C31.34 7.08 24.35 0.1 15.74 0.1 7.13 0.1 0.14 7.08 0.14 15.7c0 8.61 6.98 15.6 15.6 15.6" style="fill-rule:evenodd;fill:#f60"/><path d="m12.96 7.35c0-0.32 0.26-0.59 0.59-0.59l4.38 0c0.33 0 0.59 0.26 0.59 0.59l0 5.57 5.57 0c0.33 0 0.59 0.26 0.59 0.59l0 4.38c0 0.33-0.26 0.59-0.59 0.59l-5.57 0 0 5.57c0 0.33-0.26 0.59-0.59 0.59l-4.37 0c-0.32 0-0.59-0.26-0.59-0.59l0-5.57-5.57 0c-0.32 0-0.59-0.26-0.59-0.59l0-4.37c0-0.32 0.26-0.59 0.59-0.59l5.57 0z" style="fill-rule:evenodd;fill:#fff"/></g><g clip-path="url(#b)" fill="#fff"><defs><path d="m-2.21-3.96 150 0 0 45.93-150 0z"/></defs><clipPath><use height="100" width="100" y="0" x="0" overflow="visible" xlink:href="#c"/></clipPath><path d="m35.84 25.26c1.22 0.94 2.63 1.81 4.52 1.81 2.87 0 3.62-1.73 3.62-4.01l0-19.96 3.11 0 0 16.27c0 1.42 0 2.95-0.08 4.36-0.16 3.77-2.08 5.97-6.52 5.97-3.06 0-5.31-1.26-6.21-2.24zm29.51-5.7c0-4.72-1.37-8.02-5.19-8.02-3.73 0-5.42 3.14-5.42 7.39 0 3.89 0.79 8.49 5.27 8.49 3.73 0 5.35-3.57 5.35-7.86M60.41 9.14c2.71 0 8.06 0.87 8.06 9.75 0 7.66-3.81 10.89-8.72 10.89-4.99 0-8.06-3.38-8.06-10.45 0-8.13 4.83-10.18 8.72-10.18m26.88 19.3 0-18.74-2.99 0 0 11.71c0 2.71-1.81 4.6-4.79 4.6-4.17 0-4.44-2.28-4.44-5.27l0-11.04-3.06 0 0 11.87c0 4.48 2.16 6.09 5.5 6.45-1.93 1.26-4.32 3.54-4.32 6.72 0 3.03 1.93 4.95 5.93 4.95 4.17 0 6.68-2 7.66-5.82 0.35-1.38 0.51-3.69 0.51-5.42m-7.86 8.88c3.58 0 4.83-3.1 4.83-7.39l0-3.42c-4.72 1.97-8.13 4.09-8.13 7.82 0 1.93 1.14 2.99 3.3 2.99M99.94 9.14c-5.97 0-9.12 4.79-9.12 10.61 0 5.86 2.59 10.02 8.72 10.02 3.14 0 5.42-1.41 6.41-2.24l-1.18-2c-0.75 0.55-2.4 1.81-5.03 1.81-4.16 0-5.74-3.38-5.89-6.6l1.02 0.04c3.81 0 10.81-0.94 10.81-6.76 0-2.91-2.08-4.87-5.74-4.87m-0.16 2.28c-4.2 0-5.82 3.97-5.93 7.07l0.79 0.04c2.67 0 8.17-0.63 8.17-4.17 0-1.85-1.26-2.95-3.03-2.95m13.01 17.8 0-12.81c0-2.36 2.28-4.83 5.31-4.83 3.3 0 3.93 2.36 3.93 5.27l0 12.38 3.07 0 0-13.32c0-4.48-2.2-6.76-6.25-6.76-2.56 0-4.83 1.18-6.33 3.38l-0.35-2.83-2.63 0 0.2 2.95 0 16.58 3.07 0zm16.82-27.31 0 21.97c0 2.87 0.16 5.9 5.38 5.9 1.57 0 3.3-0.51 4.44-1.3l-0.9-2.04c-0.67 0.39-1.65 0.94-2.99 0.94-1.85 0-2.87-0.82-2.87-3.42l0-11.63 5.58 0 0-2.63-5.58 0 0-7.78zm12.22 1.8c0 1.14 0.91 1.99 2 1.99 1.08 0 1.99-0.85 1.99-1.99 0-1.12-0.91-1.97-1.99-1.97-1.09 0-2 0.85-2 1.97m0.36 0c0-0.95 0.71-1.68 1.64-1.68 0.92 0 1.63 0.73 1.63 1.68 0 0.97-0.71 1.7-1.63 1.7-0.93 0-1.64-0.73-1.64-1.7m0.86 1.17 0.36 0 0-1 0.38 0 0.63 1 0.39 0-0.66-1.02c0.35-0.04 0.61-0.21 0.61-0.63 0-0.44-0.26-0.66-0.81-0.66l-0.9 0 0 2.32zm0.36-2.02 0.48 0c0.24 0 0.51 0.05 0.51 0.36 0 0.37-0.29 0.38-0.61 0.38l-0.38 0z" clip-path="url(#d)" style="fill-rule:evenodd;fill:#fff"/></g></svg>

After

Width:  |  Height:  |  Size: 3.2 KiB

View File

@ -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)`

View File

@ -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`.

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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)

View File

@ -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
---
<div id="indextagline">
@ -15,7 +12,7 @@ Reimagining <a href="http://tools.ietf.org/html/rfc4510" id="indextaglink">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?

View File

@ -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.

View File

@ -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

View File

@ -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):