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');

  # 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 = shift;
    $xrd->extension(-HostMeta);
    print $xrd->host;
  });

Fetches an XRD document from a given resource and returns it as XML::Loy::XRD document.

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.

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-2013, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl.

cpanm Mojolicious::Plugin::XRD

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