The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

PERRETTDL / Articulate-0.005 / lib / Articulate / Service.pm 

            

              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
—
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
—
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
—
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
—
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

              
package Articulate::Service;
use strict;
use warnings;
use Articulate::Syntax;
# The following provide objects which must be created on a per-request basis
use Articulate::Request;
use Articulate::Response;
use Moo;
with 'Articulate::Role::Service';
use Try::Tiny;
use Scalar::Util qw(blessed);
use Exporter::Declare;
default_exports qw(articulate_service);
=head1 NAME
Articulate::Service - provide an API to all the core Articulate
features.
=cut
=head1 DESCRIPTION
The Articulate Service provides programmatic access to all the core
features of the Articulate app. It is the intermediary between the
B<routes> and all other B<components>.
Mostly, you will want to be calling the service in routes, for
instance:
  get 'zone/:zone_name/article/:article_name' => sub {
    my ($zone_name, $article_name) = param('zone_name'), param('article_name');
    return $self->process_request ( read => "/zone/$zone_name/article/$article_name' )
  }
However, you may also want to call it from one-off scripts, tests,
etc., especially where you want to perform tasks which you don't want
to make available in routes, or where you are already in a perl
environment and mapping to the HTTP layer would be a distraction. In
theory you could create an application which did not have any web
interface at all using this service, e.g. a command-line app on a
shared server.
=cut
sub articulate_service {
  __PACKAGE__->new(@_);
}
has providers => (
  is      => 'rw',
  default => sub { [] },
  coerce  => sub { instantiate_array(@_) },
);
=head3 process_request
  my $response = service->process_request($request);
  my $response = service->process_request($verb => $data);
This is the primary method of the service: Pass in an
Articulate::Request object and the Service will produce a Response
object to match.
Alternatively, if you pass a string as the first argument, the request
will be created from the verb and the data.
Which verbs are handled, what data they require, and how they will be
processed are determined by the service providers you have set up in
your config: C<process_request> passes the request to each of the
providers in turn and asks them to process the request.
Providers can decline to process the request by returning undef, which
will cause the service to offer the requwst to the next provider.
Note that a provider MAY act on a request and still return undef, e.g.
to perform logging, however it is discouraged to perform acctions which
a user would typically expect a response from (e.g. a create action
should return a response and not just pass to a get to confirm it has
successfully created what it was suppsed to).
=cut
sub process_request {
  my $self       = shift;
  my @underscore = @_;   # because otherwise the try block will eat it
  my $request;
  my $response = new_response error => {
    error => Articulate::Error::NotFound->new(
      { simple_message => 'No appropriate Service Provider found' }
    )
  };
  try {
    if ( ref $underscore[0] ) {
      $request = $underscore[0];
    }
    else {               # or accept $verb => $data
      $request = new_request(@underscore);
    }
    foreach my $provider ( @{ $self->providers } ) {
      $provider->app( $self->app );
      my $resp = $provider->process_request($request);
      if ( defined $resp ) {
        $response = $resp;
        last;
      }
    }
  }
  catch {
    local $@ = $_;
    if ( blessed $_ and $_->isa('Articulate::Error') ) {
      $response = new_response error => { error => $_ };
    }
    else {
      $response =
        new_response error => { error =>
          Articulate::Error->new( { simple_message => 'Unknown error' . $@ } )
        };
    }
  };
  return $response;
}
=head3 enumerate_verbs
  my @verbs = @{ $self->enumerate_verbs };
Returns an arrayref of verbs which at list one provider will process.
=cut
sub enumerate_verbs {
  my $self  = shift;
  my $verbs = {};
  foreach my $provider ( @{ $self->providers } ) {
    $verbs->{$_}++ foreach keys %{ $provider->verbs };
  }
  return [ sort keys %$verbs ];
}
=head1 SEE ALSO
=over
=item * L<Articulate::Role::Service>
=item * L<Articulate::Request>
=item * L<Articulate::Response>
=back
=cut
1;