chickadee » estraier-client

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

estraier-client

Description

A pure Scheme implementation of the Hyper Estraier P2P protocol.

Author

Peter Bex

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

list-documents base-uri node #!key max prevprocedure

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

put-document base-uri node contents attribsprocedure

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

update-attributes base-uri node attribsprocedure

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

delete-document base-uri node #!key id uriprocedure

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

find-documents

find-documents base-uri node #!key phrase attr-phrases order max skip distinct depth wwidth hwidth awidth options auxiliary maskprocedure

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

get-document base-uri node #!key id uriprocedure

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

document-attribute base-uri node attrib #!key id uriprocedure

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

document-keywords base-uri node #!key id uriprocedure

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

document-uri->id base-uri node uriprocedure

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

register-admin-user base-uri node nameprocedure

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

register-guest-user base-uri node nameprocedure

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

unregister-user

register-guest-user base-uri node nameprocedure

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

get-node-info

get-node-info base-uri nodeprocedure

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

get-cache-usage base-uri nodeprocedure

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

optimize-node

optimize-node base-uri nodeprocedure

Optimize the node's database.

sync-node

sync-node base-uri nodeprocedure

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

list-nodes base-uriprocedure
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




add-node base-uri name #!optional labelprocedure


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




delete-node base-uri nameprocedure


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




clear-node base-uri nameprocedure


Remove all documents from the node identified by name.
list-users




list-users base-uriprocedure


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




add-user base-uri username password #!key flags fullname miscprocedure


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




delete-user base-uri usernameprocedure


Delete the user with the given username from the master.
shutdown-master




shutdown-master base-uriprocedure


Shutdown the master server.
sync-all-nodes




sync-all-nodes base-uriprocedure


Synchronize databases of all nodes to disk.
backup-master




backup-master base-uriprocedure


Synchronize all databases to disk and make a full backup.
rotate-log




rotate-log base-uriprocedure


Rotate the master's log.
Other procedures
These procedures are not likely to be very useful, but they are provided for completeness.
read-draft




read-attributes inportprocedure


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




read-attributes inportprocedure


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




write-draft outport contents attributesprocedure


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




write-attributes outport attributesprocedure


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


License
 Copyright (c) 2009-2012 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.




Contents »