basis/furnace/auth/providers/providers-docs.factor

   1 USING: help.markup help.syntax strings ;
   2 IN: furnace.auth.providers
   3
   4 HELP: user
   5 { $class-description "The class of users. Instances have the following slots:"
   6 { $table
   7     { { $slot "username" } { "The username, used to identify the user for login purposes" } }
   8     { { $slot "realname" } { "The user's real name, optional" } }
   9     { { $slot "password" } { "The user's password, encoded with a checksum" } }
  10     { { $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" } }
  11     { { $slot "email" } { "The user's e-mail address, optional" } }
  12     { { $slot "ticket" } { "Used for password recovery" } }
  13     { { $slot "capabilities" } { "A sequence of capabilities; see " { $link "furnace.auth.capabilities" } } }
  14     { { $slot "profile" } { "A hashtable with webapp-specific configuration" } }
  15     { { $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" } }
  16     { { $slot "changed?" } { "A boolean indicating whether the user has changed since being retrieved from the database" } }
  17 } } ;
  18
  19 HELP: add-user
  20 { $values { "provider" "an authentication provider" } { "user" user } }
  21 { $description "A utility word which calls " { $link new-user } " and throws an error if the user already exists." } ;
  22
  23 HELP: get-user
  24 { $values { "username" string } { "provider" "an authentication provider" } { "user/f" { $maybe user } } }
  25 { $contract "Looks up a username in the authentication provider." } ;
  26
  27 HELP: new-user
  28 { $values { "user" user } { "provider" "an authentication provider" } { "user/f" { $maybe user } } }
  29 { $contract "Adds a new user to the authentication provider. Outputs " { $link f } " if a user with this username already exists." } ;
  30
  31 HELP: update-user
  32 { $values { "user" user } { "provider" "an authentication provider" } }
  33 { $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." } ;
  34
  35 ARTICLE: "furnace.auth.providers.protocol" "Authentication provider protocol"
  36 "The " { $vocab-link "furnace.auth.providers" } " vocabulary implements a protocol for persistence and authentication of users."
  37 $nl
  38 "The class of users:"
  39 { $subsections user }
  40 "Generic protocol:"
  41 { $subsections
  42     get-user
  43     new-user
  44     update-user
  45 } ;
  46
  47 ABOUT: "furnace.auth.providers.protocol"