From 7a26f30d852774d842dcc724b8e2a7e13be0b97d Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@slava-pestovs-macbook-pro.local>
Date: Sun, 16 Nov 2008 07:19:05 -0600
Subject: [PATCH] Documentation for furnace.auth.providers
---
.../auth/providers/assoc/assoc-docs.factor | 14 ++++++
.../furnace/auth/providers/db/db-docs.factor | 13 ++++++
.../auth/providers/null/null-docs.factor | 10 +++++
.../auth/providers/providers-docs.factor | 45 +++++++++++++++++++
4 files changed, 82 insertions(+)
create mode 100644 basis/furnace/auth/providers/assoc/assoc-docs.factor
create mode 100644 basis/furnace/auth/providers/db/db-docs.factor
create mode 100644 basis/furnace/auth/providers/null/null-docs.factor
create mode 100644 basis/furnace/auth/providers/providers-docs.factor
diff --git a/basis/furnace/auth/providers/assoc/assoc-docs.factor b/basis/furnace/auth/providers/assoc/assoc-docs.factor
new file mode 100644
index 0000000000..61c2ac4eed
--- /dev/null
+++ b/basis/furnace/auth/providers/assoc/assoc-docs.factor
@@ -0,0 +1,14 @@
+USING: help.markup help.syntax io.streams.string ;
+IN: furnace.auth.providers.assoc
+
+HELP: <users-in-memory>
+{ $values { "provider" users-in-memory } }
+{ $description "Creates a new authentication provider which stores the usernames and passwords in an associative mapping." } ;
+
+ARTICLE: "furnace.auth.providers.assoc" "In-memory authentication provider"
+"The " { $vocab-link "furnace.auth.providers.assoc" } " vocabulary implements an authentication provider which looks up usernames and passwords in an associative mapping."
+{ $subsection users-in-memory }
+{ $subsection <users-in-memory> }
+"The " { $slot "assoc" } " slot of the " { $link users-in-memory } " tuple maps usernames to checksums of passwords." ;
+
+ABOUT: "furnace.auth.providers.assoc"
diff --git a/basis/furnace/auth/providers/db/db-docs.factor b/basis/furnace/auth/providers/db/db-docs.factor
new file mode 100644
index 0000000000..219edf9490
--- /dev/null
+++ b/basis/furnace/auth/providers/db/db-docs.factor
@@ -0,0 +1,13 @@
+USING: help.markup help.syntax ;
+IN: furnace.auth.providers.db
+
+HELP: users-in-db
+{ $class-description "Singleton class implementing the database authentication provider." } ;
+
+ARTICLE: "furnace.auth.providers.db" "Database authentication provider"
+"The " { $vocab-link "furnace.auth.providers.db" } " vocabulary implements an authentication provider which looks up authentication requests in the " { $snippet "USERS" } " table of the current database. The database schema is Factor-specific, and the table should be initialized by calling"
+{ $code "users create-table" }
+"The authentication provider class:"
+{ $subsection users-in-db } ;
+
+ABOUT: "furnace.auth.providers.db"
diff --git a/basis/furnace/auth/providers/null/null-docs.factor b/basis/furnace/auth/providers/null/null-docs.factor
new file mode 100644
index 0000000000..100b16c7d3
--- /dev/null
+++ b/basis/furnace/auth/providers/null/null-docs.factor
@@ -0,0 +1,10 @@
+USING: help.markup help.syntax ;
+IN: furnace.auth.providers.null
+
+HELP: no-users
+{ $class-description "Singleton class implementing the dummy authentication provider." } ;
+
+ARTICLE: "furnace.auth.providers.null" "Dummy authentication provider"
+"The " { $vocab-link "furnace.auth.providers.null" } " vocabulary implements an authentication provider which refuses all authentication requests. It is only useful for testing purposes." ;
+
+ABOUT: "furnace.auth.providers.null"
diff --git a/basis/furnace/auth/providers/providers-docs.factor b/basis/furnace/auth/providers/providers-docs.factor
new file mode 100644
index 0000000000..5d15bf4f65
--- /dev/null
+++ b/basis/furnace/auth/providers/providers-docs.factor
@@ -0,0 +1,45 @@
+USING: help.markup help.syntax strings ;
+IN: furnace.auth.providers
+
+HELP: user
+{ $class-description "The class of users. Instances have the following slots:"
+{ $table
+ { { $slot "username" } { "The username, used to identify the user for login purposes" } }
+ { { $slot "realname" } { "The user's real name, optional" } }
+ { { $slot "password" } { "The user's password, encoded with a checksum" } }
+ { { $slot "salt" } { "A random salt prepended to the password to ensure that two users with the same plain-text password still have different checksum output" } }
+ { { $slot "email" } { "The user's e-mail address, optional" } }
+ { { $slot "ticket" } { "Used for password recovery" } }
+ { { $slot "capabilities" } { "A sequence of capabilities; see " { $link "furnace.auth.capabilities" } } }
+ { { $slot "profile" } { "A hashtable with webapp-specific configuration" } }
+ { { $slot "deleted" } { "A boolean indicating whether the user is active or not. This allows a user account to be deactivated without removing the user from the database" } }
+ { { $slot "changed?" } { "A boolean indicating whether the user has changed since being retrieved from the database" } }
+} } ;
+
+HELP: add-user
+{ $values { "provider" "an authentication provider" } { "user" user } }
+{ $description "A utility word which calls " { $link new-user } " and throws an error if the user already exists." } ;
+
+HELP: get-user
+{ $values { "username" string } { "provider" "an authentication provider" } { "user/f" { $maybe user } } }
+{ $contract "Looks up a username in the authentication provider." } ;
+
+HELP: new-user
+{ $values { "user" user } { "provider" "an authentication provider" } { "user/f" { $maybe user } } }
+{ $contract "Adds a new user to the authentication provider. Outputs " { $link f } " if a user with this username already exists." } ;
+
+HELP: update-user
+{ $values { "user" user } { "provider" "an authentication provider" } }
+{ $contract "Stores a user back to an authentication provider after being changed. This is a no-op with in-memory providers; providers which use an external store will save the user in this word. " } ;
+
+ARTICLE: "furnace.auth.providers.protocol" "Authentication provider protocol"
+"The " { $vocab-link "furnace.auth.providers" } " vocabulary implements a protocol for persistence and authentication of users."
+$nl
+"The class of users:"
+{ $subsection user }
+"Generic protocol:"
+{ $subsection get-user }
+{ $subsection new-user }
+{ $subsection update-user } ;
+
+ABOUT: "furnace.auth.providers.protocol"