[catagits/Catalyst-Controller-DBIC-API.git] / lib / Catalyst / Controller / DBIC / API / RequestArguments.pm

package Catalyst::Controller::DBIC::API::RequestArguments;

#ABSTRACT: Provides Request argument validation
use MooseX::Role::Parameterized;
use Catalyst::Controller::DBIC::API::Types(':all');
use MooseX::Types::Moose(':all');
use Scalar::Util('reftype');
use Data::Dumper;
use namespace::autoclean;

use Catalyst::Controller::DBIC::API::JoinBuilder;


=attribute_private search_validator

A Catalyst::Controller::DBIC::API::Validator instance used solely to validate search parameters

=cut

with 'MooseX::Role::BuildInstanceOf' =>
{
    'target' => 'Catalyst::Controller::DBIC::API::Validator',
    'prefix' => 'search_validator',
};

=attribute_private select_validator

A Catalyst::Controller::DBIC::API::Validator instance used solely to validate select parameters

=cut

with 'MooseX::Role::BuildInstanceOf' =>
{
    'target' => 'Catalyst::Controller::DBIC::API::Validator',
    'prefix' => 'select_validator',
};

=attribute_private prefetch_validator

A Catalyst::Controller::DBIC::API::Validator instance used solely to validate prefetch parameters

=cut

with 'MooseX::Role::BuildInstanceOf' =>
{
    'target' => 'Catalyst::Controller::DBIC::API::Validator',
    'prefix' => 'prefetch_validator',
};

parameter static => ( isa => Bool, default => 0 );

role {
    
    my $p = shift;
    
    if($p->static)
    {
        requires qw/check_has_relation check_column_relation/;
    }
    else
    {
        requires qw/_controller check_has_relation check_column_relation/;
    }

=attribute_public count is: ro, isa: Int

count is the number of rows to be returned during paging

=cut

    has 'count' =>
    (
        is => 'ro',
        writer => '_set_count',
        isa => Int,
        predicate => 'has_count',
    );

=attribute_public page is: ro, isa: Int

page is what page to return while paging

=cut

    has 'page' =>
    (
        is => 'ro',
        writer => '_set_page',
        isa => Int,
        predicate => 'has_page',
    );

=attribute_public ordered_by is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/OrderedBy>

ordered_by is passed to ->search to determine sorting

=cut

    has 'ordered_by' =>
    (
        is => 'ro',
        writer => '_set_ordered_by',
        isa => OrderedBy,
        predicate => 'has_ordered_by',
        coerce => 1,
        default => sub { $p->static ? [] : undef },
    );

=attribute_public groupd_by is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/GroupedBy>

grouped_by is passed to ->search to determine aggregate results

=cut

    has 'grouped_by' =>
    (
        is => 'ro',
        writer => '_set_grouped_by',
        isa => GroupedBy,
        predicate => 'has_grouped_by',
        coerce => 1,
        default => sub { $p->static ? [] : undef },
    );

=attribute_public prefetch is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/Prefetch>

prefetch is passed to ->search to optimize the number of database fetches for joins

=cut

    has prefetch =>
    (
        is => 'ro',
        writer => '_set_prefetch',
        isa => Prefetch, 
        default => sub { $p->static ? [] : undef },
        coerce => 1,
        trigger => sub
        {
            my ($self, $new) = @_;
            if($self->has_prefetch_allows and @{$self->prefetch_allows})
            {
                foreach my $pf (@$new)
                {
                    if(HashRef->check($pf))
                    {
                        die qq|'${\Dumper($pf)}' is not an allowed prefetch in: ${\join("\n", @{$self->prefetch_validator->templates})}|
                            unless $self->prefetch_validator->validate($pf)->[0];
                    }
                    else
                    {
                        die qq|'$pf' is not an allowed prefetch in: ${\join("\n", @{$self->prefetch_validator->templates})}|
                            unless $self->prefetch_validator->validate({$pf => 1})->[0];
                    }
                }
            }
            else
            {
                return if not defined($new);
                die 'Prefetching is not allowed' if @$new;
            }
        },
    );

=attribute_public prefetch_allows is: ro, isa: ArrayRef[ArrayRef|Str|HashRef]

prefetch_allows limits what relations may be prefetched when executing searches with joins. This is necessary to avoid denial of service attacks in form of queries which would return a large number of data and unwanted disclosure of data.

Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator.

    prefetch_allows => [ 'cds', { cds => tracks }, { cds => producers } ] # to be explicit
    prefetch_allows => [ 'cds', { cds => '*' } ] # wildcard means the same thing

=cut

    has prefetch_allows =>
    (
        is => 'ro',
        writer => '_set_prefetch_allows',
        isa => ArrayRef[ArrayRef|Str|HashRef], 
        default => sub { [ ] },
        predicate => 'has_prefetch_allows',
        trigger => sub
        {
            my ($self, $new) = @_;

            sub check_rel {
                my ($self, $rel, $static) = @_;
                if(ArrayRef->check($rel))
                {
                    foreach my $rel_sub (@$rel)
                    {
                        $self->check_rel($rel_sub, $static);
                    }
                }
                elsif(HashRef->check($rel))
                {
                    while(my($k,$v) = each %$rel)
                    {
                        $self->check_has_relation($k, $v, undef, $static);
                    }
                    $self->prefetch_validator->load($rel);
                }
                else
                {
                    $self->check_has_relation($rel, undef, undef, $static);
                    $self->prefetch_validator->load($rel);
                }
            }

            foreach my $rel (@$new)
            {
                $self->check_rel($rel, $p->static);
            }
        },
    );

=attribute_public search_exposes is: ro, isa: ArrayRef[Str|HashRef]

search_exposes limits what can actually be searched. If a certain column isn't indexed or perhaps a BLOB, you can explicitly say which columns can be search and exclude that one.

Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator.

=cut

    has 'search_exposes' =>
    (
        is => 'ro',
        writer => '_set_search_exposes',
        isa => ArrayRef[Str|HashRef],
        predicate => 'has_search_exposes',
        default => sub { [ ] },
        trigger => sub
        {
            my ($self, $new) = @_;
            $self->search_validator->load($_) for @$new;
        },
    );

=attribute_public search is: ro, isa: HashRef

search contains the raw search parameters. Upon setting, a trigger will fire to format them, set search_parameters, and set search_attributes.

Please see L</generate_parameters_attributes> for details on how the format works.

=cut

    has 'search' =>
    (
        is => 'ro',
        writer => '_set_search',
        isa => SearchParameters,
        predicate => 'has_search',
        coerce => 1,
        trigger => sub
        {
            my ($self, $new) = @_;
            
            if($self->has_search_exposes and @{$self->search_exposes})
            {
                foreach my $foo (@$new)
                {
                    while( my ($k, $v) = each %$foo)
                    {
                        local $Data::Dumper::Terse = 1;
                        die qq|{ $k => ${\Dumper($v)} } is not an allowed search term in: ${\join("\n", @{$self->search_validator->templates})}|
                            unless $self->search_validator->validate({$k=>$v})->[0];
                    }
                }
            }
            else
            {
                foreach my $foo (@$new)
                {
                    while( my ($k, $v) = each %$foo)
                    {
                        $self->check_column_relation({$k => $v});
                    }
                }
            }
            
            my ($search_parameters, $search_attributes) = $self->generate_parameters_attributes($new);
            $self->_set_search_parameters($search_parameters);
            $self->_set_search_attributes($search_attributes);

        },
    );

=attribute_public search_parameters is:ro, isa: L<Catalyst::Controller::DBIC::API/Types/SearchParameters>

search_parameters stores the formatted search parameters that will be passed to ->search

=cut

    has search_parameters =>
    (
        is => 'ro',
        isa => SearchParameters,
        writer => '_set_search_parameters',
        predicate => 'has_search_parameters',
        coerce => 1,
        default => sub { [{}] },
    );

=attribute_public search_attributes is:ro, isa: HashRef

search_attributes stores the formatted search attributes that will be passed to ->search

=cut

    has search_attributes =>
    (
        is => 'ro',
        isa => HashRef,
        writer => '_set_search_attributes',
        predicate => 'has_search_attributes',
        lazy_build => 1,
    );

=attribute_public search_total_entries is: ro, isa: Int

search_total_entries stores the total number of entries in a paged search result

=cut

    has search_total_entries =>
    (
        is => 'ro',
        isa => Int,
        writer => '_set_search_total_entries',
        predicate => 'has_search_total_entries',
    );

=attribute_public select_exposes is: ro, isa: ArrayRef[Str|HashRef]

select_exposes limits what can actually be selected. Use this to whitelist database functions (such as COUNT).

Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator.

=cut

    has 'select_exposes' =>
    (
        is => 'ro',
        writer => '_set_select_exposes',
        isa => ArrayRef[Str|HashRef],
        predicate => 'has_select_exposes',
        default => sub { [ ] },
        trigger => sub
        {
            my ($self, $new) = @_;
            $self->select_validator->load($_) for @$new;
        },
    );

=attribute_public select is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/SelectColumns>

select is the search attribute that allows you to both limit what is returned in the result set, and also make use of database functions like COUNT.

Please see L<DBIx::Class::ResultSet/select> for more details.

=cut

    has select =>
    (
        is => 'ro',
        writer => '_set_select',
        isa => SelectColumns,
        predicate => 'has_select',
        default => sub { $p->static ? [] : undef },
        coerce => 1,
        trigger => sub
        {   
            my ($self, $new) = @_;
            if($self->has_select_exposes)
            {
                foreach my $val (@$new)
                {
                    die "'$val' is not allowed in a select"
                        unless $self->select_validator->validate($val);
                }
            }
            else
            {
                $self->check_column_relation($_, $p->static) for @$new;
            }
        },
    );

=attribute_public as is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/AsAliases>

as is the search attribute compliment to L</select> that allows you to label columns for object inflaction and actually reference database functions like COUNT.

Please see L<DBIx::Class::ResultSet/as> for more details.

=cut

    has as =>
    (
        is => 'ro',
        writer => '_set_as',
        isa => AsAliases,
        default => sub { $p->static ? [] : undef },
        trigger => sub
        {
            my ($self, $new) = @_;
            if($self->has_select)
            {
                die "'as' argument count (${\scalar(@$new)}) must match 'select' argument count (${\scalar(@{$self->select || []})})"
                    unless @$new == @{$self->select || []};
            }
            elsif(defined $new)
            {
                die "'as' is only valid if 'select is also provided'";
            }
        }
    );

=attribute_public joins is: ro, isa L<Catalyst::Controller::DBIC::API::Types/JoinBuilder>

joins holds the top level JoinBuilder object used to keep track of joins automagically while formatting complex search parameters.

Provides a single handle which returns the 'join' attribute for search_attributes:

    build_joins => 'joins'

=cut

    has joins =>
    (
        is => 'ro',
        isa => JoinBuilder,
        lazy_build => 1,
        handles =>
        {
            build_joins => 'joins',
        }
    );

=attribute_public request_data is: ro, isa: HashRef

request_data holds the raw (but deserialized) data for ths request

=cut

    has 'request_data' =>
    (
        is => 'ro',
        isa => HashRef,
        writer => '_set_request_data',
        trigger => sub
        {
            my ($self, $new) = @_;
            my $controller = $self->_controller;
            $self->_set_prefetch($new->{$controller->prefetch_arg}) if exists $new->{$controller->prefetch_arg};
            $self->_set_select($new->{$controller->select_arg}) if exists $new->{$controller->select_arg};
            $self->_set_as($new->{$controller->as_arg}) if exists $new->{$controller->as_arg};
            $self->_set_grouped_by($new->{$controller->grouped_by_arg}) if exists $new->{$controller->grouped_by_arg};
            $self->_set_ordered_by($new->{$controller->ordered_by_arg}) if exists $new->{$controller->ordered_by_arg};
            $self->_set_search($new->{$controller->search_arg}) if exists $new->{$controller->search_arg};
            $self->_set_count($new->{$controller->count_arg}) if exists $new->{$controller->count_arg};
            $self->_set_page($new->{$controller->page_arg}) if exists $new->{$controller->page_arg};
        }
    );

    method _build_joins => sub { return Catalyst::Controller::DBIC::API::JoinBuilder->new(name => 'TOP') };

=method_protected format_search_parameters

format_search_parameters iterates through the provided params ArrayRef, calling generate_column_parameters on each one

=cut

    method format_search_parameters => sub
    {
        $DB::single = 1;
        my ($self, $params) = @_;
        
        my $genparams = [];

        foreach my $param (@$params)
        {
            push(@$genparams, $self->generate_column_parameters($self->stored_result_source, $param, $self->joins));
        }

        return $genparams;
    };

=method_protected generate_column_parameters

generate_column_parameters recursively generates properly aliased parameters for search, building a new JoinBuilder each layer of recursion

=cut

    method generate_column_parameters => sub
    {
        $DB::single = 1;
        my ($self, $source, $param, $join, $base) = @_;
        $base ||= 'me';
        my $search_params;

        # build up condition
        foreach my $column (keys %$param)
        {
            if($source->has_relationship($column))
            {
                unless (ref($param->{$column}) && reftype($param->{$column}) eq 'HASH')
                {
                    $search_params->{join('.', $base, $column)} = $param->{$column};
                    next;
                }

                %$search_params = 
                %{
                    $self->generate_column_parameters
                    (
                        $source->related_source($column),
                        $param->{$column},
                        Catalyst::Controller::DBIC::API::JoinBuilder->new(parent => $join, name => $column),
                        $column
                    )
                };
            }
            else
            {
                $search_params->{join('.', $base, $column)} = $param->{$column};
            }
        }

        return $search_params;
    };

=method_protected generate_parameters_attributes

generate_parameters_attributes takes the raw search arguments and formats the parameters by calling format_search_parameters. Then builds the related attributes, preferring request-provided arguments for things like grouped_by over statically configured options. Finally tacking on the appropriate joins. Returns both formatted search parameters and the search attributes.

=cut

    method generate_parameters_attributes => sub
    {
        $DB::single = 1;
        my ($self, $args) = @_;

        return ( $self->format_search_parameters($args), $self->search_attributes );
    };

=method_protected _build_search_attributes

This builder method generates the search attributes

=cut

    method _build_search_attributes => sub
    {
        my ($self, $args) = @_;
        my $static = $self->_controller;
        my $search_attributes = 
        {
            group_by => $self->grouped_by || ((scalar(@{$static->grouped_by})) ? $static->grouped_by : undef),
            order_by => $self->ordered_by || ((scalar(@{$static->ordered_by})) ? $static->ordered_by : undef),
            select => $self->select || ((scalar(@{$static->select})) ? $static->select : undef),
            as => $self->as || ((scalar(@{$static->as})) ? $static->as : undef),
            prefetch => $self->prefetch || $static->prefetch || undef,
            rows => $self->count || $static->count,
            page => $self->page,
            join => $self->build_joins,
        };

        $search_attributes = 
        {   
            map { @$_ }
            grep
            {
                defined($_->[1]) 
                ? 
                    (ref($_->[1]) && reftype($_->[1]) eq 'HASH' && keys %{$_->[1]})
                    || (ref($_->[1]) && reftype($_->[1]) eq 'ARRAY' && @{$_->[1]})
                    || length($_->[1])
                :
                    undef
            }
            map { [$_, $search_attributes->{$_}] }
            keys %$search_attributes
        };


        if ($search_attributes->{page} && !$search_attributes->{rows}) {
            die 'list_page can only be used with list_count';
        }
        
        if ($search_attributes->{select}) {
            # make sure all columns have an alias to avoid ambiguous issues
            # but allow non strings (eg. hashrefs for db procs like 'count')
            # to pass through unmolested
            $search_attributes->{select} = [map { (Str->check($_) && $_ !~ m/\./) ? "me.$_" : $_ } (ref $search_attributes->{select}) ? @{$search_attributes->{select}} : $search_attributes->{select}];
        }

        return $search_attributes;
        
    };

};
=head1 DESCRIPTION

RequestArguments embodies those arguments that are provided as part of a request or effect validation on request arguments. This Role can be consumed in one of two ways. As this is a parameterized Role, it accepts a single argument at composition time: 'static'. This indicates that those parameters should be stored statically and used as a fallback when the current request doesn't provide them.

=cut


1;
Commit	Line	Data
d2739840	1	package Catalyst::Controller::DBIC::API::RequestArguments;
	2
	3	#ABSTRACT: Provides Request argument validation
	4	use MooseX::Role::Parameterized;
	5	use Catalyst::Controller::DBIC::API::Types(':all');
	6	use MooseX::Types::Moose(':all');
	7	use Scalar::Util('reftype');
	8	use Data::Dumper;
	9	use namespace::autoclean;
	10
	11	use Catalyst::Controller::DBIC::API::JoinBuilder;
	12
	13
	14	=attribute_private search_validator
	15
	16	A Catalyst::Controller::DBIC::API::Validator instance used solely to validate search parameters
	17
	18	=cut
	19
	20	with 'MooseX::Role::BuildInstanceOf' =>
	21	{
	22	'target' => 'Catalyst::Controller::DBIC::API::Validator',
	23	'prefix' => 'search_validator',
	24	};
	25
	26	=attribute_private select_validator
	27
	28	A Catalyst::Controller::DBIC::API::Validator instance used solely to validate select parameters
	29
	30	=cut
	31
	32	with 'MooseX::Role::BuildInstanceOf' =>
	33	{
	34	'target' => 'Catalyst::Controller::DBIC::API::Validator',
	35	'prefix' => 'select_validator',
	36	};
	37
	38	=attribute_private prefetch_validator
	39
	40	A Catalyst::Controller::DBIC::API::Validator instance used solely to validate prefetch parameters
	41
	42	=cut
	43
	44	with 'MooseX::Role::BuildInstanceOf' =>
	45	{
	46	'target' => 'Catalyst::Controller::DBIC::API::Validator',
	47	'prefix' => 'prefetch_validator',
	48	};
	49
	50	parameter static => ( isa => Bool, default => 0 );
	51
	52	role {
	53
	54	my $p = shift;
	55
	56	if($p->static)
	57	{
	58	requires qw/check_has_relation check_column_relation/;
	59	}
	60	else
	61	{
	62	requires qw/_controller check_has_relation check_column_relation/;
	63	}
	64
65	=attribute_public count is: ro, isa: Int
66
67	count is the number of rows to be returned during paging
68
69	=cut
70
71	has 'count' =>
72	(
73	is => 'ro',
74	writer => '_set_count',
75	isa => Int,
76	predicate => 'has_count',
77	);
78
79	=attribute_public page is: ro, isa: Int
80
81	page is what page to return while paging
82
83	=cut
84
85	has 'page' =>
86	(
87	is => 'ro',
88	writer => '_set_page',
89	isa => Int,
90	predicate => 'has_page',
91	);
92
93	=attribute_public ordered_by is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/OrderedBy>
94
95	ordered_by is passed to ->search to determine sorting
96
97	=cut
98
99	has 'ordered_by' =>
100	(
101	is => 'ro',
102	writer => '_set_ordered_by',
103	isa => OrderedBy,
104	predicate => 'has_ordered_by',
105	coerce => 1,
106	default => sub { $p->static ? [] : undef },
107	);
108
109	=attribute_public groupd_by is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/GroupedBy>
110
111	grouped_by is passed to ->search to determine aggregate results
112
113	=cut
114
115	has 'grouped_by' =>
116	(
117	is => 'ro',
118	writer => '_set_grouped_by',
119	isa => GroupedBy,
120	predicate => 'has_grouped_by',
121	coerce => 1,
122	default => sub { $p->static ? [] : undef },
123	);
124
125	=attribute_public prefetch is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/Prefetch>
126
127	prefetch is passed to ->search to optimize the number of database fetches for joins
128
129	=cut
130
131	has prefetch =>
132	(
133	is => 'ro',
134	writer => '_set_prefetch',
135	isa => Prefetch,
136	default => sub { $p->static ? [] : undef },
137	coerce => 1,
138	trigger => sub
139	{
140	my ($self, $new) = @_;
141	if($self->has_prefetch_allows and @{$self->prefetch_allows})
142	{
143	foreach my $pf (@$new)
144	{
145	if(HashRef->check($pf))
146	{
147	die qq\|'${\Dumper($pf)}' is not an allowed prefetch in: ${\join("\n", @{$self->prefetch_validator->templates})}\|
148	unless $self->prefetch_validator->validate($pf)->[0];
149	}
150	else
151	{
152	die qq\|'$pf' is not an allowed prefetch in: ${\join("\n", @{$self->prefetch_validator->templates})}\|
153	unless $self->prefetch_validator->validate({$pf => 1})->[0];
154	}
155	}
156	}
157	else
158	{
159	return if not defined($new);
160	die 'Prefetching is not allowed' if @$new;
161	}
162	},
163	);
164
165	=attribute_public prefetch_allows is: ro, isa: ArrayRef[ArrayRef\|Str\|HashRef]
166
167	prefetch_allows limits what relations may be prefetched when executing searches with joins. This is necessary to avoid denial of service attacks in form of queries which would return a large number of data and unwanted disclosure of data.
168
169	Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator.
170
171	prefetch_allows => [ 'cds', { cds => tracks }, { cds => producers } ] # to be explicit
172	prefetch_allows => [ 'cds', { cds => '*' } ] # wildcard means the same thing
173
174	=cut
175
176	has prefetch_allows =>
177	(
178	is => 'ro',
179	writer => '_set_prefetch_allows',
180	isa => ArrayRef[ArrayRef\|Str\|HashRef],
181	default => sub { [ ] },
182	predicate => 'has_prefetch_allows',
183	trigger => sub
184	{
185	my ($self, $new) = @_;
186
187	sub check_rel {
188	my ($self, $rel, $static) = @_;
189	if(ArrayRef->check($rel))
190	{
191	foreach my $rel_sub (@$rel)
192	{
193	$self->check_rel($rel_sub, $static);
194	}
195	}
196	elsif(HashRef->check($rel))
197	{
198	while(my($k,$v) = each %$rel)
199	{
200	$self->check_has_relation($k, $v, undef, $static);
201	}
202	$self->prefetch_validator->load($rel);
203	}
204	else
205	{
206	$self->check_has_relation($rel, undef, undef, $static);
207	$self->prefetch_validator->load($rel);
208	}
209	}
210
211	foreach my $rel (@$new)
212	{
213	$self->check_rel($rel, $p->static);
214	}
215	},
216	);
217
218	=attribute_public search_exposes is: ro, isa: ArrayRef[Str\|HashRef]
219
220	search_exposes limits what can actually be searched. If a certain column isn't indexed or perhaps a BLOB, you can explicitly say which columns can be search and exclude that one.
221
222	Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator.
223
224	=cut
225
226	has 'search_exposes' =>
227	(
228	is => 'ro',
229	writer => '_set_search_exposes',
230	isa => ArrayRef[Str\|HashRef],
231	predicate => 'has_search_exposes',
232	default => sub { [ ] },
233	trigger => sub
234	{
235	my ($self, $new) = @_;
236	$self->search_validator->load($_) for @$new;
237	},
238	);
239
240	=attribute_public search is: ro, isa: HashRef
241
242	search contains the raw search parameters. Upon setting, a trigger will fire to format them, set search_parameters, and set search_attributes.
243
244	Please see L</generate_parameters_attributes> for details on how the format works.
245
246	=cut
247
248	has 'search' =>
249	(
250	is => 'ro',
251	writer => '_set_search',
252	isa => SearchParameters,
253	predicate => 'has_search',
254	coerce => 1,
255	trigger => sub
256	{
257	my ($self, $new) = @_;
258
259	if($self->has_search_exposes and @{$self->search_exposes})
260	{
261	foreach my $foo (@$new)
262	{
263	while( my ($k, $v) = each %$foo)
264	{
265	local $Data::Dumper::Terse = 1;
266	die qq\|{ $k => ${\Dumper($v)} } is not an allowed search term in: ${\join("\n", @{$self->search_validator->templates})}\|
267	unless $self->search_validator->validate({$k=>$v})->[0];
268	}
269	}
270	}
271	else
272	{
273	foreach my $foo (@$new)
274	{
275	while( my ($k, $v) = each %$foo)
276	{
277	$self->check_column_relation({$k => $v});
278	}
279	}
280	}
281
282	my ($search_parameters, $search_attributes) = $self->generate_parameters_attributes($new);
283	$self->_set_search_parameters($search_parameters);
284	$self->_set_search_attributes($search_attributes);
285
286	},
287	);
288
289	=attribute_public search_parameters is:ro, isa: L<Catalyst::Controller::DBIC::API/Types/SearchParameters>
290
291	search_parameters stores the formatted search parameters that will be passed to ->search
292
293	=cut
294
295	has search_parameters =>
296	(
297	is => 'ro',
298	isa => SearchParameters,
299	writer => '_set_search_parameters',
300	predicate => 'has_search_parameters',
301	coerce => 1,
302	default => sub { [{}] },
303	);
304
305	=attribute_public search_attributes is:ro, isa: HashRef
306
307	search_attributes stores the formatted search attributes that will be passed to ->search
308
309	=cut
310
311	has search_attributes =>
312	(
313	is => 'ro',
314	isa => HashRef,
315	writer => '_set_search_attributes',
316	predicate => 'has_search_attributes',
317	lazy_build => 1,
318	);
319
320	=attribute_public search_total_entries is: ro, isa: Int
321
322	search_total_entries stores the total number of entries in a paged search result
323
324	=cut
325
326	has search_total_entries =>
327	(
328	is => 'ro',
329	isa => Int,
330	writer => '_set_search_total_entries',
331	predicate => 'has_search_total_entries',
332	);
333
334	=attribute_public select_exposes is: ro, isa: ArrayRef[Str\|HashRef]
335
336	select_exposes limits what can actually be selected. Use this to whitelist database functions (such as COUNT).
337
338	Like the synopsis in DBIC::API shows, you can declare a "template" of what is allowed (by using an '*'). Each element passed in, will be converted into a Data::DPath and added to the validator.
339
340	=cut
341
342	has 'select_exposes' =>
343	(
344	is => 'ro',
345	writer => '_set_select_exposes',
346	isa => ArrayRef[Str\|HashRef],
347	predicate => 'has_select_exposes',
348	default => sub { [ ] },
349	trigger => sub
350	{
351	my ($self, $new) = @_;
352	$self->select_validator->load($_) for @$new;
353	},
354	);
355
356	=attribute_public select is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/SelectColumns>
357
358	select is the search attribute that allows you to both limit what is returned in the result set, and also make use of database functions like COUNT.
359
360	Please see L<DBIx::Class::ResultSet/select> for more details.
361
362	=cut
363
364	has select =>
365	(
366	is => 'ro',
367	writer => '_set_select',
368	isa => SelectColumns,
369	predicate => 'has_select',
370	default => sub { $p->static ? [] : undef },
371	coerce => 1,
372	trigger => sub
373	{
374	my ($self, $new) = @_;
375	if($self->has_select_exposes)
376	{
377	foreach my $val (@$new)
378	{
379	die "'$val' is not allowed in a select"
380	unless $self->select_validator->validate($val);
381	}
382	}
383	else
384	{
385	$self->check_column_relation($_, $p->static) for @$new;
386	}
387	},
388	);
389
390	=attribute_public as is: ro, isa: L<Catalyst::Controller::DBIC::API::Types/AsAliases>
391
392	as is the search attribute compliment to L</select> that allows you to label columns for object inflaction and actually reference database functions like COUNT.
393
394	Please see L<DBIx::Class::ResultSet/as> for more details.
395
396	=cut
397
398	has as =>
399	(
400	is => 'ro',
401	writer => '_set_as',
402	isa => AsAliases,
403	default => sub { $p->static ? [] : undef },
404	trigger => sub
405	{
406	my ($self, $new) = @_;
407	if($self->has_select)
408	{
409	die "'as' argument count (${\scalar(@$new)}) must match 'select' argument count (${\scalar(@{$self->select \|\| []})})"
410	unless @$new == @{$self->select \|\| []};
411	}
412	elsif(defined $new)
413	{
414	die "'as' is only valid if 'select is also provided'";
415	}
416	}
417	);
418
419	=attribute_public joins is: ro, isa L<Catalyst::Controller::DBIC::API::Types/JoinBuilder>
420
421	joins holds the top level JoinBuilder object used to keep track of joins automagically while formatting complex search parameters.
422
423	Provides a single handle which returns the 'join' attribute for search_attributes:
424
425	build_joins => 'joins'
426
427	=cut
428
429	has joins =>
430	(
431	is => 'ro',
432	isa => JoinBuilder,
433	lazy_build => 1,
434	handles =>
435	{
436	build_joins => 'joins',
437	}
438	);
439
440	=attribute_public request_data is: ro, isa: HashRef
441
442	request_data holds the raw (but deserialized) data for ths request
443
444	=cut
445
446	has 'request_data' =>
447	(
448	is => 'ro',
449	isa => HashRef,
450	writer => '_set_request_data',
451	trigger => sub
452	{
453	my ($self, $new) = @_;
454	my $controller = $self->_controller;
455	$self->_set_prefetch($new->{$controller->prefetch_arg}) if exists $new->{$controller->prefetch_arg};
456	$self->_set_select($new->{$controller->select_arg}) if exists $new->{$controller->select_arg};
457	$self->_set_as($new->{$controller->as_arg}) if exists $new->{$controller->as_arg};
458	$self->_set_grouped_by($new->{$controller->grouped_by_arg}) if exists $new->{$controller->grouped_by_arg};
459	$self->_set_ordered_by($new->{$controller->ordered_by_arg}) if exists $new->{$controller->ordered_by_arg};
460	$self->_set_search($new->{$controller->search_arg}) if exists $new->{$controller->search_arg};
461	$self->_set_count($new->{$controller->count_arg}) if exists $new->{$controller->count_arg};
462	$self->_set_page($new->{$controller->page_arg}) if exists $new->{$controller->page_arg};
463	}
464	);
465
466	method _build_joins => sub { return Catalyst::Controller::DBIC::API::JoinBuilder->new(name => 'TOP') };
467
468	=method_protected format_search_parameters
469
470	format_search_parameters iterates through the provided params ArrayRef, calling generate_column_parameters on each one
471
472	=cut
473
474	method format_search_parameters => sub
475	{
476	$DB::single = 1;
477	my ($self, $params) = @_;
478
479	my $genparams = [];
480
481	foreach my $param (@$params)
482	{
483	push(@$genparams, $self->generate_column_parameters($self->stored_result_source, $param, $self->joins));
484	}
485
486	return $genparams;
487	};
488
489	=method_protected generate_column_parameters
490
491	generate_column_parameters recursively generates properly aliased parameters for search, building a new JoinBuilder each layer of recursion
492
493	=cut
494
495	method generate_column_parameters => sub
496	{
497	$DB::single = 1;
498	my ($self, $source, $param, $join, $base) = @_;
499	$base \|\|= 'me';
500	my $search_params;
501
502	# build up condition
503	foreach my $column (keys %$param)
504	{
505	if($source->has_relationship($column))
506	{
507	unless (ref($param->{$column}) && reftype($param->{$column}) eq 'HASH')
508	{
509	$search_params->{join('.', $base, $column)} = $param->{$column};
510	next;
511	}
512
513	%$search_params =
514	%{
515	$self->generate_column_parameters
516	(
517	$source->related_source($column),
518	$param->{$column},
519	Catalyst::Controller::DBIC::API::JoinBuilder->new(parent => $join, name => $column),
520	$column
521	)
522	};
523	}
524	else
525	{
526	$search_params->{join('.', $base, $column)} = $param->{$column};
527	}
528	}
529
530	return $search_params;
531	};
532
533	=method_protected generate_parameters_attributes
534
535	generate_parameters_attributes takes the raw search arguments and formats the parameters by calling format_search_parameters. Then builds the related attributes, preferring request-provided arguments for things like grouped_by over statically configured options. Finally tacking on the appropriate joins. Returns both formatted search parameters and the search attributes.
536
537	=cut
538
539	method generate_parameters_attributes => sub
540	{
541	$DB::single = 1;
542	my ($self, $args) = @_;
543
544	return ( $self->format_search_parameters($args), $self->search_attributes );
545	};
546
547	=method_protected _build_search_attributes
548
549	This builder method generates the search attributes
550
551	=cut
552
553	method _build_search_attributes => sub
554	{
555	my ($self, $args) = @_;
556	my $static = $self->_controller;
557	my $search_attributes =
558	{
559	group_by => $self->grouped_by \|\| ((scalar(@{$static->grouped_by})) ? $static->grouped_by : undef),
560	order_by => $self->ordered_by \|\| ((scalar(@{$static->ordered_by})) ? $static->ordered_by : undef),
561	select => $self->select \|\| ((scalar(@{$static->select})) ? $static->select : undef),
562	as => $self->as \|\| ((scalar(@{$static->as})) ? $static->as : undef),
563	prefetch => $self->prefetch \|\| $static->prefetch \|\| undef,
564	rows => $self->count \|\| $static->count,
565	page => $self->page,
566	join => $self->build_joins,
567	};
568
569	$search_attributes =
570	{
571	map { @$_ }
572	grep
573	{
574	defined($_->[1])
575	?
576	(ref($_->[1]) && reftype($_->[1]) eq 'HASH' && keys %{$_->[1]})
577	\|\| (ref($_->[1]) && reftype($_->[1]) eq 'ARRAY' && @{$_->[1]})
578	\|\| length($_->[1])
579	:
580	undef
581	}
582	map { [$_, $search_attributes->{$_}] }
583	keys %$search_attributes
584	};
585
586
587	if ($search_attributes->{page} && !$search_attributes->{rows}) {
588	die 'list_page can only be used with list_count';
589	}
590
591	if ($search_attributes->{select}) {
592	# make sure all columns have an alias to avoid ambiguous issues
593	# but allow non strings (eg. hashrefs for db procs like 'count')
594	# to pass through unmolested
595	$search_attributes->{select} = [map { (Str->check($_) && $_ !~ m/\./) ? "me.$_" : $_ } (ref $search_attributes->{select}) ? @{$search_attributes->{select}} : $search_attributes->{select}];
596	}
597
598	return $search_attributes;
599
600	};
601
602	};
603	=head1 DESCRIPTION
604
605	RequestArguments embodies those arguments that are provided as part of a request or effect validation on request arguments. This Role can be consumed in one of two ways. As this is a parameterized Role, it accepts a single argument at composition time: 'static'. This indicates that those parameters should be stored statically and used as a fallback when the current request doesn't provide them.
606
607	=cut
608
609
610	1;