File Coverage

blib/lib/Mojolicious/Plugin/Restify.pm

Criterion	Covered	Total	%
statement	91	105	86.6
branch	36	58	62.0
condition	22	51	43.1
subroutine	8	11	72.7
pod	1	1	100.0
total	158	226	69.9

package Mojolicious::Plugin::Restify;
use Mojo::Base 'Mojolicious::Plugin';

use Mojo::Util qw(camelize);

our $VERSION = '0.08';

sub register {
  my ($self, $app, $conf) = @_;

  $conf //= {};

  # default HTTP method to instance method mappings for collections
  $conf->{collection_method_map} //= {
    get  => 'list',
    post => 'create',
  };

  # default HTTP method to instance method mappings for resource elements
  $conf->{element_method_map} //= {
    delete => 'delete',
    get    => 'read',
    patch  => 'patch',
    put    => 'update',
  };

  # over defaults to the standard route condition check (allow all)
  $conf->{over} //= 'standard';

  # resource_lookup methods are added to element resource routes by default
  $conf->{resource_lookup} //= 1;

  # When adding route conditions, warn developers if the exported conditions
  # already exist.
  if (exists $app->routes->conditions->{int}) {
    $app->log->debug("The int route condition already exists, skipping");
  }
  else {
    $app->routes->add_condition(
      int => sub {
        my ($r, $c, $captures, $pattern) = @_;
        my $int
          = defined $pattern
          ? ($captures->{$pattern} // $captures->{int})
          : ($captures->{int} // '');

        return 1 if $int =~ /^\d+$/;
      }
    );
  }

  if (exists $app->routes->conditions->{standard}) {
    $app->log->debug("The standard route condition already exists, skipping");
  }
  else {
    $app->routes->add_condition(standard => sub {1});
  }

  if (exists $app->routes->conditions->{uuid}) {
    $app->log->debug("The uuid route condition already exists, skipping");
  }
  else {
    $app->routes->add_condition(
      uuid => sub {
        my ($r, $c, $captures, $pattern) = @_;
        my $uuid
          = defined $pattern
          ? ($captures->{$pattern} // $captures->{uuid})
          : ($captures->{uuid} // '');

        return 1
          if $uuid
          =~ /^[a-f0-9]{8}-?[a-f0-9]{4}-?[a-f0-9]{4}-?[a-f0-9]{4}-?[a-f0-9]{12}$/i;
      }
    );
  }

  $app->routes->add_shortcut(
    collection => sub {
      my $r       = shift;
      my $path    = shift;
      my $options = ref $_[0] eq 'HASH' ? shift : {@_};

      $options->{element} //= 1;
      $options->{route_path} = $path;
      $path =~ tr/-/_/;
      $options->{route_name}
        = $options->{prefix} ? "$options->{prefix}_$path" : $path;

      local $options->{collection_method_map} = $options->{collection_method_map}
        // $conf->{collection_method_map};

      # generate "/$path" collection route
      my $controller
        = $options->{controller} ? "$options->{controller}-$path" : $path;
      my $collection = $r->route("/$options->{route_path}")->to("$controller#");

      # Map HTTP methods to instance methods/mojo actions
      while (my ($http_method, $method) = each %{$options->{collection_method_map}}) {
        $collection->$http_method->to("#$method")
          ->name("$options->{route_name}_$method");
      }

      return $options->{element}
        ? $collection->element($options->{route_path}, $options)
        : $collection;
    }
  );

  $app->routes->add_shortcut(
    element => sub {
      my $r       = shift;
      my $path    = shift;
      my $options = ref $_[0] eq 'HASH' ? shift : {@_};

      $options->{over}            //= $conf->{over};
      $options->{placeholder}     //= ':';
      $options->{resource_lookup} //= $conf->{resource_lookup};
      $path =~ tr/-/_/;
      $options->{route_name}
        = $options->{prefix} ? "$options->{prefix}_$path" : $path;

      local $options->{element_method_map} = $options->{element_method_map}
        // $conf->{element_method_map};

      # generate "/$path/:id" element route with specific placeholder
      my $element = $r->route("/$options->{placeholder}${path}_id")
        ->over($options->{over} => "${path}_id")->name($options->{route_name});

      # Generate remaining CRUD routes for "/$path/:id", optionally creating a
      # resource_lookup method for the resource $element.
      #
      # This method allows loading an object using the :id in resource_lookup,
      # and have it accessible via the stash in DELETE, GET, PUT etc. methods
      # in your controller.
      my $under
        = $options->{resource_lookup}
        ? $element->under->to('#resource_lookup')
        ->name("$options->{route_name}_resource_lookup")
        : $element;

      # Map HTTP methods to instance methods/mojo actions
      while (my ($http_method, $method) = each %{$options->{element_method_map}}) {
        $under->$http_method->to("#$method")
          ->name("$options->{route_name}_$method");
      }

      return $element;
    }
  );

  $app->helper(
    'restify.current_id' => sub {
      my $c    = shift;
      my $name = $c->stash->{controller};
      $name =~ s,^.*\-,,;
      return $c->match->stack->[-1]->{"${name}_id"} // '';
    }
  );

  $app->helper(
    'restify.routes' => sub {
      my ($self, $r, $routes, $defaults) = @_;
      return unless $routes;

      # Allow users to simplify their route creation using an array ref!
      $routes = _arrayref_to_hashref($routes)
        if ref $routes && ref $routes eq 'ARRAY';

      $defaults //= {};
      $defaults->{resource_lookup} //= $conf->{resource_lookup};

      while (my ($name, $attrs) = each %$routes) {
        my $paths   = {};
        my $options = {%$defaults};

        if (ref $attrs eq 'ARRAY') {
          $options = {%$options, %{$attrs->[-1]}} if ref $attrs->[-1] eq 'HASH';
          $paths = shift @$attrs if ref $attrs->[0] eq 'HASH';
        }
        elsif (ref $attrs eq 'HASH') {
          $paths = $attrs;
        }

        if (scalar keys %$paths) {
          my $controller = $name;
          $controller =~ tr/-/_/;
          my $collection = $r->collection($name, {%$options, element => 0});
          my $under
            = $options->{resource_lookup}
            ? $collection->under->to($options->{controller}
            ? "$options->{controller}-$controller#resource_lookup"
            : "$controller#resource_lookup")
            ->name("${controller}_resource_lookup")
            : $collection;
          my $endpoint
            = $under->element($name, {%$options, resource_lookup => 0});
          $options->{controller}
            = $options->{controller}
            ? "$options->{controller}-$controller"
            : $controller;
          $options->{prefix}
            = $options->{prefix}
            ? "$options->{prefix}_$controller"
            : $controller;
          $self->restify->routes($endpoint, $paths, $options);
        }
        else {
          $r->collection($name, $options);
        }
      }

      return;
    }
  );
}

# Aargh eurgh ma bwains!
sub _arrayref_to_hashref {
  my $arrayref = shift;
  return {} unless defined $arrayref;

  my $hashref = {};
  for my $path (@$arrayref) {
    my $options;
    if (ref $path and ref $path eq 'ARRAY') {
      ($path, $options) = @$path;
    }
    my @parts = split '/', $path;
    if (@parts == 1) {
      $hashref->{shift @parts} = defined $options ? [undef, $options] : undef;
    }
    else {
      my $key = shift @parts;
      $hashref->{$key} //= {};
      $hashref->{$key}
        = {%{$hashref->{$key}}, %{_arrayref_to_hashref([join '/', @parts])}};
    }
  }

  return $hashref;
}

1;

=encoding utf8

=head1 NAME

Mojolicious::Plugin::Restify - Route shortcuts & helpers for REST collections

=head1 SYNOPSIS

  # Mojolicious example (Mojolicious::Lite isn't supported)
  package MyApp;
  use Mojo::Base 'Mojolicious';

  sub startup {
    my $self = shift;

    # imports the `collection' route shortcut and `restify' helpers
    $self->plugin('Restify');

    # add REST collection endpoints manually
    my $r = $self->routes;
    my $accounts = $r->collection('accounts');      # /accounts
    $accounts->collection('invoices');              # /accounts/:accounts_id/invoices

    # or add the equivalent REST routes with an ARRAYREF (the helper will
    # create chained routes from the path 'accounts/invoices' so you don't need
    # to set ['accounts', 'accounts/invoices'])
    my $r = $self->routes;
    $self->restify->routes($r, ['accounts/invoices']);

    # or add the equivalent REST routes with a HASHREF (might be easier to
    # visualise how collections are chained together)
    my $r = $self->routes;
    $self->restify->routes($r, {
      accounts => {
        invoices => undef
      }
    });
  }

Next create your controller for accounts.

  # Restify controller depicting the REST actions for the /accounts collection.
  # (The name of the controller is the Mojo::Util::camelized version of the
  # collection path.)
  package MyApp::Controller::Accounts;
  use Mojo::Base 'Mojolicious::Controller';

  sub resource_lookup {
    my $c = shift;

    # To consistenly get the element's ID relative to the resource_lookup
    # action, use the helper as shown below. If you need to access an element ID
    # from a collection further up the chain, you can access it from the stash.
    #
    # The naming convention is the name of the collection appended with '_id'.
    # E.g., $c->stash('accounts_id').
    my $account = your_lookup_account_resource_func($c->restify->current_id);

    # By stashing the $account here, it will now be available in the delete,
    # read, patch, and update actions. This resource_lookup action is optional,
    # but added to every collection by default to help reduce your code.
    $c->stash(account => $account);

    # must return a positive value to continue the dispatch chain
    return 1 if $account;

    # inform the end user that this specific resource does not exist
    $c->reply->not_found and return 0;
  }

  sub create { ... }

  sub delete { ... }

  sub list { ... }

  sub read {
    my $c = shift;

    # account was placed in the stash in the resource_lookup action
    $c->render(json => $c->stash('account'));
  }

  sub patch { ... }

  sub update { ... }

  1;

=head1 DESCRIPTION

L is a L. It simplifies
generating all of the L for a typical REST I
endpoint (e.g., C or C) and maps the common HTTP verbs
(C, C, C, C, C) to underlying controller class
methods.

For example, creating a I called C would create the
routes as shown below. N.B. The C option in the example below corresponds
to the name of a route condition. See L.

  # The collection route shortcut below creates the following routes, and maps
  # them to controllers of the camelized route's name.
  #
  # Pattern           Methods   Name                        Class::Method Name
  # -------           -------   ----                        ------------------
  # /accounts         *         accounts
  #   +/              GET       "accounts_list"             Accounts::list
  #   +/              POST      "accounts_create"           Accounts::create
  #   +/:accounts_id  *         "accounts"
  #     +/            *         "accounts_resource_lookup"  Accounts::resource_lookup
  #       +/          DELETE    "accounts_delete"           Accounts::delete
  #       +/          GET       "accounts_read"             Accounts::read
  #       +/          PATCH     "accounts_patch"            Accounts::patch
  #       +/          PUT       "accounts_update"           Accounts::update

  # expects the element id (:accounts_id) for this collection to be a uuid
  my $route = $r->collection('accounts', over => 'uuid');

L tries not to make too many assumptions, but the
author's recent experience writing a REST-based API using L has
helped shaped this plugin, and might unwittingly express some of his bias.

=head1 HELPERS

L implements the following helpers.

=head2 restify->current_id

  my $id = $c->restify->current_id;

Returns the I id at the current point in the dispatch chain.

This is the only way to guarantee the correct I's resource ID in a
L I. The C I,
which is added by default in both L and L, is
added at different positions of the dispatch chain. As such, the router might
not have added the value of any placeholders to the
L yet.

=head2 restify->routes

This helper is a wrapper around the L route shortcut. It
facilitates creating REST I using either an C or
C.

It takes a L object, the I to create, and optionally
I which are passed to the L route shortcut.

  # /accounts
  # /accounts/1234
  $self->restify->routes($self->routes, ['accounts'], {over => 'int'});

  # /invoices
  # /invoices/76be1f53-8363-4ac6-bd83-8b49e07b519c
  $self->restify->routes($self->routes, ['invoices'], {over => 'uuid'});

Maybe you want to chain them.

  # /accounts
  # /accounts/1234
  #   /accounts/1234/invoices
  #   /accounts/1234/invoices/76be1f53-8363-4ac6-bd83-8b49e07b519c
  $self->restify->routes(
    $self->routes,
    ['accounts', ['accounts/invoices' => {over => 'uuid'}]],
    {over => 'int'}
  );

=over

=item ARRAYREF

Using the elements of the array, invokes L, passing any route-
specific options.

It will automatically create and chain parent routes if you pass a full path
e.g., C<['a/very/long/path']>. This is equivalent to the shell command
C.

  my $restify_routes = [
    # /area-codes
    #   /area-codes/:area_codes_id/numbers
    'area-codes/numbers',
    # /news
    'news',
    # /payments
    ['payments' => {over => 'int'}],   # overrides default uuid route condition
    # /users
    #   /users/:users_id/messages
    #     /users/:users_id/messages/:messages_id/recipients
    'users/messages/recipients',
  ];

  $self->restify->routes($self->routes, $restify_routes, {over => 'uuid'});

In its most basic form, C routes are created from a C.

  # /accounts
  my $restify_routes = ['accounts'];

=item HASHREF

Using the key/values of the hash, invokes L, passing any route-
specific options.

It automatically chains routes to each parent, and progressively builds a
namespace as it traverses through each key.

N.B., This was implemented before the C version, and is arguably a bit
more confusing. It might be dropped in a later version to simplify the API.

  my $restify_routes = {
    # /area-codes
    #   /area-codes/:area_codes_id/numbers
    'area-codes' => {
      'numbers' => undef
    },
    # /news
    'news' => undef,
    # /payments
    'payments' => [undef, {over => 'int'}],   # overrides default uuid route condition
    # /users
    #   /users/:users_id/messages
    #     /users/:users_id/messages/:messages_id/recipients
    'users' => {
      'messages' => {
        'recipients' => undef
      }
    },
  };

  $self->restify->routes($self->routes, $restify_routes, {over => 'uuid'});

=back

=head1 METHODS

L inherits all methods from L
and implements the following new ones.

=head2 register

  $plugin->register(Mojolicious->new);

Register plugin in L application.

=head1 ROUTE CONDITIONS

L implements the following route conditions. These
conditions can be used with the C option in the L shortcut.

Checks are made for the existence of the C, C and C
conditions before adding them. This allows you to replace them with your own
conditions of the same name by creating them before registering this plugin.

See L to add your own.

=head2 int

  # /numbers/1        # GOOD
  # /numbers/0        # GOOD
  # /numbers/one      # BAD
  # /numbers/-1       # BAD
  # /numbers/0.114    # BAD (the standard :placeholder notation doesn't allow a '.')

  my $r = $self->routes;
  $r->collection('numbers', over => 'int');

A L route condition (see L) which
restricts a route's I's I id to whole positive integers
which are C= 0>.

=head2 standard

  my $r = $self->routes;
  $r->collection('numbers', over => 'standard');

A I's I resource ID is captured using
L. This route condition
allows everything the standard placeholder allows, which is similar to the
regular expression C<([^/.]+)>.

This is the default I option for a L.

=head2 uuid

  # /uuids/8ebef0d0-d6cf-11e4-8830-0800200c9a66     GOOD
  # /uuids/8EBEF0D0-D6CF-11E4-8830-0800200C9A66     GOOD
  # /uuids/8ebef0d0d6cf11e488300800200c9a66         GOOD
  # /uuids/malformed-uuid                           BAD

  my $r = $self->routes;
  $r->collection('uuids', over => 'uuid');

A L route condition (see L) which
restricts a route's I's I id to UUIDs only (with or without
the separating hyphens).

=head1 ROUTE SHORTCUTS

L implements the following route shortcuts.

=head2 collection

  my $r = $self->routes;
  $r->collection('accounts');
  $r->collection('accounts', collection_method_map => {delete => 'delete_collection'});
  $r->collection('accounts', controller            => 'differentmodule');
  $r->collection('accounts', element               => 0);
  $r->collection('accounts', element_method_map    => {get => 'read'});
  $r->collection('accounts', over                  => 'uuid');
  $r->collection('accounts', placeholder           => '*');
  $r->collection('accounts', prefix                => 'v1');
  $r->collection('accounts', resource_lookup       => '0');

A L which helps
create the most common REST L for a
I endpoint and its associated I.

A I endpoint (e.g., C) supports I (C) and
I (C) actions. The I's I (e.g.,
C) supports I (C), I (C),
I (C), and I (C) actions.

By default, every HTTP request to a I's I is routed through
a C I (see L). This
helps reduce the process of looking up a I's resource to a single
location. See L for an example of its use.

=head4 options

The following options allow a I to be fine-tuned.

=over

=item collection_method_map

  $r->collection(
    'invoices',
    {
      collection_method_map => {
        get  => 'list',
        post => 'create',
        # delete => 'delete_collection',  # delete all-the-things!
        # put    => 'update_collection'   # update all-the-things!
      }
    }
  );

The above represents the default HTTP method mappings for C. It's
possible to change the mappings globally (when importing the plugin) or per
collection (as above).

These HTTP method mappings only apply to the C. e.g., C.
Please see C if you want to apply different HTTP mappings
to an C like C.

=item controller

  # collection doesn't build a namespace for subroutes by default
  my $accounts = $r->collection('accounts');    # MyApp::Controller::Accounts
  $accounts->collection('invoices');            # MyApp::Controller::Invoices

  # collection can build namespaces, but can be difficult to keep track of. Use
  # the restify helper if namespaces are important to you.
  #
  # MyApp::Controller::Accounts
  my $accounts = $r->collection('accounts');
  # MyApp::Controller::Accounts::Invoices
  my $invoices = $accounts->collection('invoices', controller => 'accounts');
  # MyApp::Controller::Accounts::Invoices::Foo
  $invoices->collection('foo', controller => 'accounts-invoices');

Prepends the controller name (which is automatically generated based on the path
name) with this option value if present. Used internally by L to build
a perlish namespace from the paths. L does not build a namespace by
default.

=item element

  # GET,POST                      /messages     200
  # DELETE,GET,PATCH,PUT,UPDATE   /messages/1   200
  $r->collection('messages');     # element routes are created by default

  # GET,POST                      /messages     200
  # DELETE,GET,PATCH,PUT,UPDATE   /messages/1   404
  $r->collection('messages', element => 0);

Enables or disables chaining an I to the I. Disabling the
element portion of a I means that only the I and I
actions will be created.

=item element_method_map

  $r->collection(
    'invoices',
    {
      element_method_map  => {
        'delete' => 'delete',
        'get'    => 'read',
        'patch'  => 'patch',
        'put'    => 'update',
      }
    }
  );

The above represents the default HTTP method mappings. It's possible to change
the mappings globally (when importing the plugin) or per collection (as above).

These HTTP method mappings only apply to the C's C. e.g.,
C.

=item over

  $r->collection('invoices', over => 'int');
  $r->collection('invoices', over => 'standard');
  $r->collection('accounts', over => 'uuid');

Allows a I's I to be restricted to a specific data type
using Mojolicious' route conditions. L, L and L are
added automatically if they don't already exist.

=item placeholder

  # /versions/:versions_id      { versions_id => '123'}
  # /versions/#versions_id      { versions_id => '123.00'}
  # /versions/*versions_id      { versions_id => '123.00/1'}

The placeholder is used to capture the I id within a route. It can be
one of C, C or C. You might need to
adjust the placholder option in certain scenarios, but the C
placeholder should suffice for most normal REST endpoints.

  $r->collection('/messages', placeholder => ':');

I are chained to a I using the standard placeholder by
default. They match all characters except C and C<.>. See
L.

  $r->collection('/relaxed-messages', placeholder => '#');

Placeholders can be relaxed, matching all characters expect C. Useful if you
need to capture a domain name within a route. See
L.

  $r->collection('/wildcard-messages', placeholder => '*');

Or they can be greedy, matching everything, inclusive of C and C<.>. Useful
if you need to capture everything within a route. See
L.

=item prefix

  # without a prefix
  $r->collection('invoices');
  say $c->url_for('invoices', invoices_id => 1);

  # with a prefix
  $r->collection('invoices', prefix => 'v1');
  say $c->url_for('v1_invoices', invoices_id => 1);

Adds a prefix to the automatically generated route
L for each I and I
I.

=item resource_lookup

  $r->collection('nolookup', resource_lookup => 0);

Enables or disables adding a C I to the I of
the I.

=back

=head2 element

  my $r    = $self->routes;
  my $news = $r->get('/news')->to('foo#news');
  $news->element('news');

A L called internally
by L to add the I routes to a I. You shouldn't
need to call this shortcut directly.

When an element is added to a I's route, the resource ID is captured
using a standard placeholder by default.

=head1 CREDITS

In alphabetical order:

=over 2

Castaway

Dragoș-Robert Neagu

=back

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015-2017, Paul Williams.

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

=head1 AUTHOR

Paul Williams

=head1 SEE ALSO

L, L, L.

=cut