NAME

Starch::Remote::Service - A plack application for running the Starch remote service.

SYNOPSIS

Create a starch-remote.psgi file:

use Starch::Remote::Service;

Starch::Remote::Service->new(
    starch => {
        store => { class => '::Memory' },
        plugins => ['::CookieArgs'],
    },
)->to_app();

Then launch it:

plackup starch-remote.psgi

DESCRIPTION

This Plack service exposes Starch in a way that allows for a mostly hands-free integration of Starch with disparate HTTP applications, including applications written in other languages. Having a central service for managing sessions can be especially important in polyglot organizations, allowing for web applications to be written in multiple languages yet still share the same session backend logic.

INTEGRATION

The typical setup is an arbitrary web application which needs to access sessions as part of handling a request. This web application has no knowledge of how sessions are stored or how they are tracked. In order to retrofit the web application to use the Starch remote a request would be handled like this:

1. A request is begun in the web application.

2. The web application issues a POST subrequest agains the /begin endpoint of the Starch remote service. The POST subrequest includes all HTTP headers that the web application received in it's request.

3. The Starch remote's response includes the "id" in Starch::State and the "data" in Starch::State of the session. If no id could be derived from the headers supplied in the subrequest then a new state will be created and it's id and empty data will be returned.

4. The web application's main logic steps in and handles the request. The web application will read, and potentially, write to the data hash as needed.

5. When the web application is ready to send response headers back to the client it first issues a POST subrequest agains the /finish endpoint of the Starch remote service. The POST subrequest includes the id and data originally supplied in step #3, but the data may have been modified during step #4.

6. The Starch remote's response to the subrequest contains HTTP headers for the web application to include in it's response to the request.

7. And, finally, the web application returns a response.

See "ENDPOINTS" for more, including example request and response JSON bodies.

LOGGING

Log::Any is used for all logging.

CLIENTS

Starch::Remote::Client is a client for this service.

Catalyst::Plugin::Starch::Remote causes Catalyst to use this service for session retrieval and storage.

REQUIRED ARGUMENTS

starch

Starch::Remote::Service->new(
    starch => {
        store => { class => '::Memory' },
        plugins => [ '::CookieArgs' ],
    },
);

This may be either a Starch object, or hashref arguments to create one.

The Starch::Plugin::CookieArgs plugin is required.

OPTIONAL_ARGUMENTS

validate_res

Starch::Remote::Service->new(
    starch => ...,
    validate_res => 1,
);

When enabled this causes the response data to be validated. By default this is off. This is made available for debugging and unit testing.

Failed response validation will cause a 500 to be returned and for a detailed error log to be recorded.

ENDPOINTS

POST /begin

Expects the request content to be a JSON object with a single key, headers, containing an array of all HTTP headers that the caller received.

On success, returns a 200 response with the content containing a JSON object with the id key set to the ID of the Starch state, and a data key containing the state data.

Example request content:

{
    "headers": [
        "Acccept-Language", "en-us",
        "Cookie", "session=4f29abc0917cb119a86c8b15e70503a4380667bf"
    ]
}

Example response content:

{
    "id": "4f29abc0917cb119a86c8b15e70503a4380667bf",
    "data": {"foo":1}
}

If the request content does not contain JSON, or the JSON is invalid, then a 400 response will be returned and the content will be a string explaining the issue.

POST /finish

Expects the request content to be a JSON object with the id key set to the ID of the Starch state, and the data key set to the new state data to be saved.

On success, returns a 200 response with the content containing a JSON object with the headers key set to an array of key/value pairs.

Example request content:

{
    "id": "4f29abc0917cb119a86c8b15e70503a4380667bf",
    "data": {"foo":1,"bar":2}
}

Example response content:

{
    "headers": [
        "Set-Cookie",
        "session=4f29abc0917cb119a86c8b15e70503a4380667bf; domain=.example.com; path=/; ..."
    ]
}

If the request content does not contain JSON, or the JSON is invalid, then a 400 response will be returned and the content will be a string explaining the issue.

AUTHOR

Aran Clary Deltac <bluefeet@gmail.com>

ACKNOWLEDGEMENTS

Thanks to ZipRecruiter for encouraging their employees to contribute back to the open source ecosystem. Without their dedication to quality software development this distribution would not exist.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.