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