/ 
Whelk-1.01
River stage zero No dependents
/ Whelk::Wrapper

NAME

Whelk::Wrapper - Base class for wrappers

SYNOPSIS

package Whelk::Wrapper::MyWrapper;

use Kelp::Base 'Whelk::Wrapper';

# at the very least, there three methods must be implemented

sub wrap_server_error
{
	my ($self, $error) = @_;

	...;
}

sub wrap_success
{
	my ($self, $data) = @_;

	...;
}

sub build_response_schemas
{
	my ($self, $endpoint) = @_;

	...;
}

DESCRIPTION

Whelk::Wrapper is a base class for wrappers. Wrapper's job is to wrap the endpoint handler in necessary logic: validating request and response data, adding extra data to responses and error handling. Wrappers do not handle encoding requests and responses (for example with JSON), that's a job for Whelk::Formatter.

In addition, wrapper decides how to treat failures. It defines schemas for errors with status classes 400 and 500 and uses those instead of response schema defined for the endpoint in case an error occurs.

Whelk implements two basic wrappers which can be used out of the box: Whelk::Wrapper::Simple (the default) and Whelk::Wrapper::WithStatus. They are very similar and differ in how they wrap the response data - WithStatus wrapper introduces an extra boolean status field to every response.

It should be pretty easy to subclass a wrapper if needed. Take a look at the built in subclasses and at the code of this class to get the basic idea.

METHODS

The only wrapper method called from outside is wrap. All the other methods are helpers which make it easier to adjust the behavior without rewriting it from scratch.

The base Whelk::Wrapper class does not implement wrap_server_error, wrap_success and build_response_schemas methods - they have to be implemented in a subclass.

wrap

my $wrapped_sub = $wrapper->wrap($sub);

Takes a reference to a subroutine and returns a reference to another subroutine. The returned subroutine is an outer code to be called by Kelp as route handler. It does all the Whelk-specific behavior and calls the inner subroutine to get the actual result of the API call.

wrap_response

my $response = $wrapper->wrap_response($response, $http_code);

This method is used to wrap $response returned by Kelp route handler. The default implementation takes a look at the $http_code and fires one of wrap_success (for codes 2XX), wrap_server_error (for codes 5XX) or wrap_client_error (for codes 4XX). The wrapped response must be matching the respone schema defined in "build_response_schemas" or else an exception will be thrown.

build_response_schemas

$wrapper->build_response_schemas($endpoint)

Takes an object of Whelk::Endpoint class and should set response_schemas field of that object. That field must contain a hash reference where each key will be response code and each value will be a schema built using "build" in Whelk::Schema. Regular success schema should nest the value of $endpoint->response schema inside of it.

The status codes need not to be exact. By default, only their class is important (200, 400 or 500). The exact semantics of that mapping is defined in another method, "map_code_to_schema".

If the schema from $endpoint->response is empty via $endpoint->response->empty then it must be added to response_schemas as is to correctly be mapped to 204 No Body HTTP status.

inhale_request

This is a helper method which validates the request. It may be overridden for extra behavior.

To ensure request_body method works, it must set $app->req->stash->{request} after validating and cleaning the request body.

execute

This is a helper method which runs the actual route handler in a try/catch block. It may be overridden for extra behavior.

prepare_response

This is a helper method which prepares a response to be passed to "exhale_response". It may be overridden for extra behavior.

exhale_response

This is a helper method which validates and returns a response. It may be overridden for extra behavior.

map_code_to_schema

This is a helper method which decides which key from response_schemas of the endpoint to use based on HTTP code of the response. It may be overridden for extra behavior.

on_error

This is a helper method which decides what to do when an unexpected error occurs. By default, it creates an application log and modifies the result message to return a stock HTTP message like Internal Server Error. It may be overridden for extra behavior.