The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

ircindexer-server-json - Serve IRC::Indexer JSON over HTTP

SYNOPSIS

  ## Create example httpd.cf:
  $ ircindexer-examplecf -t httpd -o httpd.cf
  $ $EDITOR httpd.cf

  ## Add some servers:
  $ mkdir -p networks/cobaltirc
  $ ircindexer-examplecf -t spec -o \
      networks/cobaltirc/phoenix.xyloid.org
  $ $EDITOR networks/cobaltirc/phoenix.xyloid.org

  ## Start server:
  $ ircindexer-server-json -c httpd.cf

DESCRIPTION

Indexes sets of servers in parallel via IRC::Indexer, exporting information as JSON via HTTP for ease of retrieval.

Uses POEx::HTTP::Server to provide HTTP daemon functionality.

JSON is encoded by forked IRC::Indexer::Process::JSONify instances.

Intended to serve as the back-end to a presentation system for the data collected. See IRC::Indexer::POD::ExampleClients for some examples of ways to make use of the exported data on the client side.

Fetching JSON

Networks or servers that are configured but not yet trawled will report a 404 error with a string indicating that the trawl run is pending.

You can check 404s for network/server requests for status information.

If the first word of the 404 content is PENDING, the requested item is pending a trawler run.

If the first word of the 404 content is NO_SUCH, the requested item is not being indexed by the trawler.

List

A hash containing networks and servers scheduled for trawling is available via /list:

  ## JSON hash containing network -> server mapping of
  ## configured trawlers:
  http://my.server:8700/list

Note that this is the list of configured network -> server maps, not necessarily the list of trawled servers.

That is to say, the network names are guaranteed valid, but the server names may not be available under the /network/<NET>/server/ tree; for a list of servers available for retrieval, see "Servers", below.

Networks

Network information hashes are exported via /network/ routes:

  ## JSON array of available trawled networks:
  http://my.server:8700/network

  ## JSON Network Info hash for 'CobaltIRC':
  http://my.server:8700/network/CobaltIRC
  
  ## Compressed:
  http://my.server:8700/network/CobaltIRC?gzip

These are indexed by their configured network name.

Servers

Specific server hashes as described in IRC::Indexer::Trawl::Bot are exported via /network/<NETNAME>/server/<SERVERNAME>:

  ## List of trawled servers for this network:
  http://my.server:8700/network/CobaltIRC/server

  ## Trawl results from a single server:
  http://my.server:8700/network/CobaltIRC/server/eris.oppresses.us
  
  ## Compressed:
  http://my.server:8700/network/CobaltIRC/server/eris.oppresses.us?gzip

Note that servers are not available for retrieval until they are trawled; depending on trawl intervals, it may take some time to cycle through all listed servers for a network.

Also note that servers are indexed by their reported server name -- not necessarily the name specified in their configuration.

Stats

Stats regarding the running instance are exported via /stats:

  http://my.server:8700/stats

Reloading networks

You can reload the existing networks set and force a rehash by sending a SIGHUP to the server.

Your NetworkDir will be re-scanned and any removed networks will be pulled from the trawl cache. All networks will have their trawl runs rescheduled immediately -- in other words, SIGHUP can also be used to force a refresh.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

http://www.cobaltirc.org