Dezi::Architecture - all about the Dezi innards
This document describes the Dezi architecture.
The chief assumption in this document is that you are using the Apache Lucy library (http://lucy.apache.org/) backend via Search::OpenSearch::Engine::Lucy. Lucy is the default engine type for Dezi. In theory, any Search::OpenSearch::Engine subclass could work, though not all have full REST support.
The other assumptions are that you have some understanding of the HTTP/1.1 protocol, and some understanding of object-oriented software design, particularly in Perl.
Dezi is a Search::OpenSearch::Server::Plack application designed first for ease-of-use and extensibility, through a centralized configuration file. Dezi implements a HTTP-based search server with a REST orientation.
The name Dezi was chosen because it is short and easy to pronounce. Search::OpenSearch::Server::Plack is a mouthful. I was inspired by the Starman naming rationale, and I used to watch a lot of black-and-white TV re-runs as a kid.
Dezi is a short name with a long list of dependencies.
Dezi integrates the Search::OpenSearch set of modules with Swish3 and Apache Lucy.
The primary dependency is Search::OpenSearch::Server::Plack, which Dezi::Server subclasses directly.
Search::OpenSearch::Server::Plack is a Plack::Component that implements some basic HTTP request handling and delegates most of the hard work to a Search::OpenSearch::Engine, in our case Search::OpenSearch::Engine::Lucy.
Search::OpenSearch::Engine::Lucy, like all Search::OpenSearch::Engine subclasses, delegates to one or more task-specific classes: for searching, Dezi::Lucy::Searcher; for indexing, Dezi::Lucy::Indexer.
All the Dezi::App components rely on Swish3. Swish3 is the third major version of Swish-e (http://swish3.dezi.org/). The SWISH::3 module is a Perl binding to the libswish3 C library, which is primarily a document parser built on top of libxml2.
Apache Lucy (http://lucy.apache.org/) is the underlying information retrieval library. It does all the hard work. Everything else is built on top of or extends Lucy with the intent of making the out-of-the-box experience as painless as possible, and filling in some of the usability gaps.
Keep one thing in mind: the only web-specific pieces of Dezi are the Plack components. Everything else is transport-agnostic. For example, the deziapp command (mentioned in the Dezi::Tutorial) comes with Dezi::App, and uses the same Dezi::App modules to index and search that Dezi does. Dezi is a REST server version of the deziapp command-line tool.
If that didn't make things any clearer, go back and read this section again. Even if it doesn't get clearer, the module names will at least start to become more familiar.
First, read Dezi::Config. Then come back here.
The heart of Dezi is the configuration file. Dezi is designed so that you don't have to write any code, unless you want to. Nearly every dependency component can be configured via the Dezi::Config file.
Because there are so many components, please consult the documentation specific to each component for particular options. Those components should be noted in the Dezi::Config SYNOPSIS.
Dezi's architecture is oriented toward the REpresentational State Transfer (REST) model. See http://en.wikipedia.org/wiki/Representational_state_transfer.
You should interpret "oriented toward" as a subtle caveat that Dezi doesn't claim to be purely RESTful in its implementation. While most REST constraints are respected and supported, there are certain optional optimizations that violate one or more of the REST constraints.
For example, the auto_commit Engine feature, which gives the ability to COMMIT or ROLLBACK one or more POST requests, could be said to violate the Stateless REST constraint. In its transaction implementation, Dezi follows a more RPC-style model with REST-like semantics (i.e., you can use the COMMIT or ROLLBACK HTTP method, which is neither part of the HTTP spec nor RESTful, but which does emphasize the noun/verb separation of HTTP method and URI).
Strong emphasis is put on exercising the full HTTP/1.1 specification, including the use of HTTP methods to indicate server actions and proper (we hope!) HTTP response codes.
An incoming HTTP request is parsed and routed according to its method. GET requests are always idempotent. POST, PUT and DELETE requests are not: they can alter the state of resources on the server.
The following examples show how Dezi interprets requests:
GET /search?q=foo # return search results for 'foo'
POST /index/foo # add or update document 'foo'
PUT /index/foo # add (only) document 'foo'
GET /index/foo # return document 'foo'
DELETE /index/foo # remove document 'foo'
COMMIT /index # write pending changes
POST /commit # same as COMMIT /index
ROLLBACK /index # abort pending changes
POST /rollback # same as ROLLBACK /index
GET /ui # return Dezi::UI HTML
The actual paths are configurable. See Dezi::Config.
Dezi delegates all search responses to Search::OpenSearch::Response objects. The default response type is JSON. You can use the t GET param to change that type per-request, or use the default_response_format engine configuration option to set the default. See Dezi::Config, Search::OpenSearch::Engine and Search::OpenSearch::Response.
All non-idempotent responses use the JSON format, and indicate both the success boolean and code HTTP status as part of the JSON string.
The evolution of the Dezi application is ongoing and I welcome your feedback. See the SUPPORT section below for how to get involved.
Peter Karman, <karman at cpan.org>
<karman at cpan.org>
Please report any bugs or feature requests to bug-dezi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dezi. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-dezi at rt.cpan.org
You can find this documentation with the perldoc command.
You can also look for information at:
#dezisearch at freenode
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
Copyright 2012 Peter Karman.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
Dezi::Server, Dezi::Config, Search::OpenSearch, SWISH::3, Dezi::App, Plack, Lucy
To install Dezi, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.