NAME¶
Atompub::Server - A server for the Atom Publishing Protocol
SYNOPSIS¶
package My::Server;
use base qw(Atompub::Server);
sub handle_request {
my($server) = @_;
$server->authenticate or return;
my $method = $server->request_method;
if ($method eq 'POST') {
return $server->new_post;
}
...
}
my %Passwords;
sub password_for_user {
my($server, $username) = @_;
$Passwords{$username};
}
sub new_post {
my($server) = @_;
my $entry = $server->atom_body or return;
# $entry is an XML::Atom::Entry object.
# ... Save the new entry ...
}
package main;
my $server = My::Server->new;
$server->run;
DESCRIPTION¶
Atompub::Server provides a base class for Atom Publishing Protocol servers. It
handles all core server processing, and Basic and WSSE authentication. It can
also run as either a mod_perl handler or as part of a CGI program.
It does not provide functions specific to any particular implementation, such as
creating an entry, retrieving a list of entries, deleting an entry, etc.
Implementations should subclass Atompub::Server, overriding the
"handle_request" method, and handle all functions such as this
themselves.
Atompub::Server extends XML::Atom::Server, and basically provides same
functions. However, this module has been fixed based on the Atom Publishing
Protocol described at <
http://www.ietf.org/rfc/rfc5023.txt>, and
supports Basic authentication rather than WSSE.
SUBCLASSING¶
Request Handling¶
Subclasses of Atompub::Server must override the "handle_request"
method to perform all request processing. The implementation must set all
response headers, including the response code and any relevant HTTP headers,
and should return a scalar representing the response body to be sent back to
the client.
For example:
sub handle_request {
my($server) = @_;
my $method = $server->request_method;
if ($method eq 'POST') {
return $server->new_post;
}
# ... handle GET, PUT, etc
}
sub new_post {
my($server) = @_;
my $entry = $server->atom_body or return;
# Implementation-specific
my $id = save_this_entry($entry);
my $location = join '/', $server->uri, $id;
my $etag = calc_etag($entry);
$server->response_header(Location => $location);
$server->response_header(ETag => $etag );
$server->response_code(RC_CREATED);
$server->response_content_type('application/atom+xml;type=entry');
# Implementation-specific
return serialize_entry($entry);
}
Authentication¶
Servers that require authentication should override the
"password_for_user" method. Given a username (from the Authorization
or WSSE header), "password_for_user" should return that user's
password in plaintext. If the supplied username doesn't exist in your user
database or alike, just return "undef".
For example:
my %Passwords = (foo => 'bar'); # The password for "foo" is "bar".
sub password_for_user {
my($server, $username) = @_;
$Passwords{$username};
}
- •
- Basic Authentication
realm must be assigned before authentication for Basic
authentication.
$server->realm('MySite');
If your server runs as a CGI program and authenticates by Basic
authenticate, you should use authentication mechanism of the http server,
like ".htaccess".
- •
- WSSE Authentication
Any pre-configuration is not required for WSSE. The password returned from
"password_for_user" will be combined with the nonce and the
creation time to generate the digest, which will be compared with the
digest sent in the WSSE header.
METHODS¶
Atompub::Server provides a variety of methods to be used by subclasses for
retrieving headers, content, and other request information, and for setting
the same on the response.
$server->realm¶
If called with an argument, sets the
realm for Basic authentication.
Returns the current
realm that will be used when receiving requests.
$server->get_auth_info¶
$server->authenticate¶
$server->auth_failure($status, $message)¶
oether methods¶
Descriptions are found in XML::Atom::Server.
USAGE¶
Once you have defined your server subclass, you can set it up either as a CGI
program or as a mod_perl handler.
See XML::Atom::Server in details.
SEE ALSO¶
XML::Atom XML::Atom::Service Atompub Catalyst::Controller::Atompub
AUTHOR¶
Takeru INOUE, <takeru.inoue _ gmail.com>
LICENCE AND COPYRIGHT¶
Copyright (c) 2007, Takeru INOUE "<takeru.inoue _ gmail.com>".
All rights reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself. See perlartistic.
DISCLAIMER OF WARRANTY¶
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE
PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR
CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO
LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER
SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.