estraier-client
  1. estraier-client
    1. Description
    2. Author
    3. Repository
    4. Requirements
    5. Documentation
    6. Node API
      1. list-documents
      2. put-document
      3. update-attributes
      4. delete-document
      5. find-documents
      6. get-document
      7. document-attribute
      8. document-keywords
      9. document-uri->id
      10. register-admin-user
      11. register-guest-user
      12. unregister-user
      13. get-node-info
      14. get-cache-usage
      15. optimize-node
      16. sync-node
    7. Master API
      1. list-nodes
      2. add-node
      3. delete-node
      4. clear-node
      5. list-users
      6. add-user
      7. delete-user
      8. shutdown-master
      9. sync-all-nodes
      10. backup-master
      11. rotate-log
    8. Other procedures
      1. read-draft
      2. read-attributes
      3. write-draft
      4. write-attributes
    9. Changelog
    10. License

Description

A pure Scheme implementation of the Hyper Estraier P2P protocol.

Author

Peter Bex

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/estraier-client

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Requirements

Requires the http-client, uri-common and intarweb eggs.

Documentation

All procedures in estraier-client accept a base URI as their first argument. This can be either an uri-common object or a regular string representing an URI. This URI acts as the base URI for the server, which will get the master or node path appended. For example, the base uri http://admin:password@localhost:1978 can be used both for master control commands as well as node commands. In case of a master command, it will be appended to so we get http://admin:password@localhost:1978/master?action=<command>. In case of a node command, it will get appended to with the node name so we get http://admin:password@localhost:1978/node/mynode/<command>.

In error situations, this library will signal one of the following type of conditions:

(exn estraier-client args)
Arguments are invalid
(exn estraier-client auth)
Authentication failed
(exn estraier-client perm)
Permission denied
(exn estraier-client node)
Node does not exist
(exn estraier-client server)
Internal server error

Node API

list-documents

[procedure] (list-documents base-uri node #!key max prev)

List the documents known to the node. Returns a list of alists containing the system attributes of each node: @id, @uri, @digest, @cdate, @mdate, @adate, @title, @author, @type, @lang, @genre, @size, @weight and @misc. All attribute values are returned as plain strings.

The max argument controls the maximum number of results returned by this procedure. It defaults to 10. To get the next set of results, supply the prev option. Its value should be the value of the @uri attribute of the last document in the previous result set.

put-document

[procedure] (put-document base-uri node contents attribs)

Store a new document, or replace an existing document at node.

contents is a list of strings representing lines in the document. attribs is an alist of document attributes. The @uri attribute must be present or the document will not be stored! If the @uri is identical to an existing document, it is replaced.

Example:

(put-document "http://admin:admin@localhost:1978" "testnode"
              '("Hello there, this is another quick test") '((@uri . "test1")))

update-attributes

[procedure] (update-attributes base-uri node attribs)

Update an existing document's attributes at the given node. attribs is an alist containing the new attributes for the document. The document is identified by the @uri attribute.

The attributes in the document are completely replaced by attribs. This means that any attributes existing in the document but missing from attribs will be removed from the document.

(update-attributes "http://admin:admin@localhost:1978" "testnode"
                  '((@uri . "test1") (my-attribute . "some-value")))

delete-document

[procedure] (delete-document base-uri node #!key id uri)

Delete the document identified by id or uri at node. You must supply one of id or uri, but not both.

find-documents

[procedure] (find-documents base-uri node #!key phrase attr-phrases order max skip distinct depth wwidth hwidth awidth options auxiliary mask)

Search for documents, using the options provided. If phrase is not supplied and attr-phrases is an empty list, zero documents are returned. Otherwise, phrase and attr-phrases must all match a document in order for it to be returned. In other words, phrase is ANDed with all the attr-phrases. The keys have the following meaning:

phrase
This is the search phrase which is matched against the documents (a string)
attr-phrases
These are the search phrases which are matched against the document attributes (a list of strings). This list can contain up to 10 search conditions, but not more. It defaults to the empty list.
order
The order in which the results should be returned (a string).
max
The maximum number of results returned (a number). If not supplied, it defaults to 10.
skip
The number of documents to skip in the result set (a number). Defaults to 0.
distinct
The attribute name on which to filter distinctly (a symbol or string).
depth
The depth of the meta-search (a number). Defaults to 0.
wwidth
The whole width (in characters) of search result snippets (a number). Default depends on server configuration. If zero, no snippets are returned. If negative, whole documents are returned.
hwidth
The width of strings (in characters) in the snippet in the beginning of the text (a number). Default depends on server configuration.
awidth
The width of strings (in characters) around the snipper (a number). Default depends on server configuration.
options
Options for the search condition. (TODO)
auxiliary
Permission to adopt result of the auxiliary index (a number). By default, it is 32. (TODO)
mask
The mask of search targets (a number). 1 means the node itself, 2 means the first link, 4 means the second link, 8 means the third link, and power values of 2 and their summation compose the mask. (TODO)

See the documentation for search conditions for information on the syntax of phrase, attr-phrases and order.

This procedure returns two values. The first value is a list containing the documents (the actual search results), the second value is a list with meta-information about the search result set.

The documents are pairs with the matched snippets (a list of pairs) as car and the attributes (an alist) as cdr. The car of a snippet is either a string to be highlighted (the part of the string that was in the search phrase) or #f if no appropriate highlighting can be made. The cdr of a snippet is a matched string.

Example:

(put-document "http://admin:admin@localhost:1978" "testnode"
              '("Hello there, this is another quick test") '((@uri . "test1")))
(find-documents "http://admin:admin@localhost:1978" "testnode"
                phrase: "quick test")
=>
((((#f . "Hello there, this is another ") ("quick test" . "quick test"))
  (#nodelabel . "testnode")
  (#nodescore . "10758")
  (#nodeurl . "http://localhost:1978/node/testnode")
  (@digest . "ec0e90969320452b97f55f97ad3a5cc7")
  (@id . "8")
  (@uri . "test1")))
((VERSION "1.0")
 (NODE "http://localhost:1978/node/testnode")
 (HIT "1")
 (HINT#1 "test" "1")
 (DOCNUM "1")
 (WORDNUM "8")
 (TIME "0.004907")
 (TIME#i "0.000597")
 (TIME#0 "0.000749")
 (LINK#0 "http://localhost:1978/node/testnode" "testnode" "10000" "1" "8" "9129518" "1")
 (VIEW "SNIPPET"))

get-document

[procedure] (get-document base-uri node #!key id uri)

Fetch the document identified by id or uri at node. You must supply one of id or uri, but not both. Returns two values: the document's contents (a list of strings, representing lines in the document) and the document's attributes (an alist with symbols as keys and strings as values).

Example:

(get-document "http://admin:admin@localhost:1978" "testnode" uri: "test1")
=>
("Hello there, this is another quick test")
((#nodelabel . "testnode")
 (#nodeurl . "http://localhost:1978/node/testnode")
 (@digest . "34736f47d003748e7c6896a5931070dc")
 (@id . "8")
 (@uri . "test1"))

document-attribute

[procedure] (document-attribute base-uri node attrib #!key id uri)

Fetch the attribute with name attrib from the document identified by id or uri at node. You must supply one of id or uri, but not both. attrib may be either a symbol or a string. This procedure returns a string with the attribute's contents.

Note: If the attribute does not exist, an exception of type (exn estraier-client args) is thrown.

Example:

(document-attribute "http://admin:admin@localhost:1978" "testnode"
                    '@digest uri: "test1")
=>
"34736f47d003748e7c6896a5931070dc"

document-keywords

[procedure] (document-keywords base-uri node #!key id uri)

Fetch the keywords that belong to the document identified by id or uri at node. You must supply one of id or uri, but not both. Returns a list of pairs. The car is a string with the keyword, the cdr is a number representing the keyword's assigned score.

Example:

(document-keywords "http://admin:admin@localhost:1978" "testnode" uri: "test1")
=>
(("another" . 7882)
 ("there" . 1)
 ("," . 1)
 ("this" . 1)
 ("is" . 1)
 ("quick" . 1)
 ("hello" . 1)
 ("test" . 1))

document-uri->id

[procedure] (document-uri->id base-uri node uri)

Look up the ID of a document by its uri at node. Returns a string with the document's ID.

Example:

(document-uri->id "http://admin:admin@localhost:1978" "testnode" "test1")
=>
"8"

register-admin-user

[procedure] (register-admin-user base-uri node name)

Register the user with the given name to be an admin for node. This does not affect the user's guest status.

register-guest-user

[procedure] (register-guest-user base-uri node name)

Register the user with the given name to be a guest for node. This does not affect the user's admin status.

unregister-user

[procedure] (register-guest-user base-uri node name)

Remove a user with the given name from the node's list of known users.

get-node-info

[procedure] (get-node-info base-uri node)

Get information about the given node. Returns an alist containing the following keys:

name
The name of the node (string)
label
The label of the node (string)
document-count
The number of documents in the node's database (number)
word-count
The number of unique words in the node's database (number)
size
The size of the node's database (number) (in bytes?)
admin-users
The names of the users that are admin to this node (list of strings)
guest-users
The names of the users that are guests to this node (list of strings)

get-cache-usage

[procedure] (get-cache-usage base-uri node)

Get the cache usage for the given node. Returns a number that indicates the cache size (in bytes?).

optimize-node

[procedure] (optimize-node base-uri node)

Optimize the node's database.

sync-node

[procedure] (sync-node base-uri node)

Synchronize updating of the node's database. If you do not perform this, search results or listings might not include all the latest additions to the database.

Master API

list-nodes

[procedure] (list-nodes base-uri)

List all nodes known to the node master. Returns a list of node info alists. Each node info alist contains the following symbolic keys:

name
The name of the node (string)
label
The label of the node (string)
document-count
The number of documents in the node's database (number)
word-count
The number of unique words in the node's database (number)
size
The size of the node's database (number) (in bytes?)

add-node

[procedure] (add-node base-uri name [label])

Create a new node server with the given name and label and add it to the master's pool of nodes. If label is omitted, it defaults to name.

delete-node

[procedure] (delete-node base-uri name)

Delete the node server identified by name from the master's pool of nodes. This action destroys the node and all its contents.

clear-node

[procedure] (clear-node base-uri name)

Remove all documents from the node identified by name.

list-users

[procedure] (list-users base-uri)

List all users known to the master. Returns a list of user info alists. Each user info alist contains the following symbolic keys:

name
The name of the user
password
The encrypted password
flags
The user flags. The string contains "b" if the user is banned or "s" if it is a superuser.
fullname
The full name of the user.
misc
Miscellaneous information about the user.

All values are strings.

add-user

[procedure] (add-user base-uri username password #!key flags fullname misc)

Add a user with the given username and password to the master. The optional flags key is a string containing a "b" if the user is to be banned or an "s" if the user is to be a superuser. The fullname specifies the user's full name and misc specifies miscellaneous information about the user.

delete-user

[procedure] (delete-user base-uri username)

Delete the user with the given username from the master.

shutdown-master

[procedure] (shutdown-master base-uri)

Shutdown the master server.

sync-all-nodes

[procedure] (sync-all-nodes base-uri)

Synchronize databases of all nodes to disk.

backup-master

[procedure] (backup-master base-uri)

Synchronize all databases to disk and make a full backup.

rotate-log

[procedure] (rotate-log base-uri)

Rotate the master's log.

Other procedures

These procedures are not likely to be very useful, but they are provided for completeness.

read-draft

[procedure] (read-attributes inport)

Read a document in "draft format" from the input-port inport. Returns two values: the document contents (a list of strings representing the lines in the docuemnt) and the document's attributes (an alist).

read-attributes

[procedure] (read-attributes inport)

Like read-attributes, except this only reads the attributes and returns only one value: an alist with the attributes.

write-draft

[procedure] (write-draft outport contents attributes)

Write out a document in "draft format" to the specified output port outport. attributes is an alist with the attributes of the document, contents is a list of strings with the lines in the document.

write-attributes

[procedure] (write-attributes outport attributes)

Like write-draft, except this only writes the attributes part (the "header", in a way) of the draft.

Changelog

License

 
 Copyright (c) 2009-2018 Peter Bex
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.