manwar / mojolicious-plugin-xrd

Render XRD documents with Mojolicious

NAME

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

SYNOPSIS

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

# In controller
my $xrd = $c->new_xrd;
$xrd->subject('acct:[email protected]');
$xrd->link(profile => '/me.html');

# Render as XRD or JRD, depending on request
$c->reply->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:[email protected]</Subject>
#   <Link href="/me.html"
#         rel="profile" />
# </XRD>

# or:
# Content-Type: application/jrd+json
# {
#   "subject":"acct:[email protected]",
#   "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.

reply->xrd

# In Controllers
$self->reply->xrd( $xrd );
$self->reply->xrd( undef, 'acct:[email protected]' );

The helper reply->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-2018, 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.