NAME

Mojolicious::Plugin::XRD - XRD Document Handling with Mojolicious

SYNOPSIS

  # Mojolicious
  $self->plugin('XRD');

  # In controller
  my $xrd = $c->new_xrd;
  $xrd->subject('acct:akron@sojolicio.us');
  $xrd->link(profile => '/me.html');

  # Render as XRD or JRD, depending on request
  $c->render_xrd($xrd);

  # Content-Type: application/xrd+xml
  # <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  # <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"
  #      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  #   <Subject>acct:akron@sojolicio.us</Subject>
  #   <Link href="/me.html"
  #         rel="profile" />
  # </XRD>

  # or:
  # Content-Type: application/jrd+json
  # {
  #   "subject":"acct:akron@sojolicio.us",
  #   "links":[{"rel":"profile","href":"\/me.html"}]
  # }

  my $gmail_hm = $c->get_xrd('//gmail.com/.well-known/host-meta');
  print $gmail_hm->link('lrdd')->attrs('template');
  # http://profiles.google.com/_/webfinger/?q={uri}

DESCRIPTION

Mojolicious::Plugin::XRD is a plugin to support Extensible Resource Descriptor documents through XML::Loy::XRD.

Additionally it supports the rel parameter of the WebFinger specification.

METHODS

register

  # Mojolicious
  $app->plugin('XRD');

  # Mojolicious::Lite
  plugin 'XRD';

Called when registering the plugin.

HELPERS

new_xrd

  # In Controller:
  my $xrd = $self->new_xrd;

Returns a new XML::Loy::XRD object without extensions.

get_xrd

  # In Controller:
  my $xrd = $self->get_xrd('//gmail.com/.well-known/host-meta');

  # In array context
  my ($xrd, $headers) = $self->get_xrd('//gmail.com/.well-known/host-meta');

  # With relation restrictions and security flag
  $xrd = $self->get_xrd('https://gmail.com/.well-known/host-meta' => ['lrdd']);

  # With additional headers
  $xrd = $self->get_xrd('https://gmail.com/.well-known/host-meta' => {
    'X-My-HTTP-Header' => 'Just for Fun'
  } => ['lrdd']);

  # Non-blocking
  $self->get_xrd('//gmail.com/.well-known/host-meta' => sub {
    my ($xrd, $headers) = @_;
    $xrd->extension(-HostMeta);
    print $xrd->host;
  });

Fetches an XRD document from a given resource and returns it as XML::Loy::XRD document. In array context it additionally returns the response headers as a Mojo::Headers object.

Expects a valid URL. In case no scheme is given (e.g., //gmail.com), the method will first try to fetch the resource with https and on failure fetches the resource with http, supporting redirections. If the given scheme is https, the discovery will be secured, even disallowing redirections. The second argument may be a hash reference containing HTTP headers. An additional array reference may limit the relations to be retrieved (see the WebFinger specification for further explanation).

This method can be used in a blocking or non-blocking way. For non-blocking retrieval, pass a callback function as the last argument. As the first passed response is the XML::Loy::XRD document, you have to use an offset of 0 in begin for parallel requests using Mojo::IOLoop::Delay.

This method is experimental and may change wihout warnings.

render_xrd

  # In Controllers
  $self->render_xrd( $xrd );
  $self->render_xrd( undef, 'acct:acron@sojolicio.us' );

The helper render_xrd renders an XRD object either in xml or in json notation, depending on the request. If an XRD object is empty, it renders a 404 error and accepts a second parameter as the subject of the error document.

CAVEATS

There are different versions of XRD and JRD with different MIME types defined. In some cases you may have to change the MIME type manually.

DEPENDENCIES

Mojolicious, Mojolicious::Plugin::XML::Loy.

AVAILABILITY

  https://github.com/Akron/Mojolicious-Plugin-XRD

COPYRIGHT AND LICENSE

Copyright (C) 2011-2014, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

cpanm Mojolicious::Plugin::XRD

perl -MCPAN -e shell
install Mojolicious::Plugin::XRD