NAME

    Protocol::Tus - Tus protocol handling

VERSION

    This document describes Protocol::Tus version 0.003.

SYNOPSIS

       use Protocol::Tus;
    
       my $tus = Protocol::Tus->new(
          model => {
             class => 'Protocol::Tus::LocalDir',
             args  => { root => '/path/to/somewhere' },
          }
       );
    
       # assume we have some way of getting requests... This method takes
       # care of everything, including X-HTTP-Method-Override
       my $request = get_some_input_request();
    
       my $response = $tus->HTTP_request(
          method  => $request->{method},   # POST, PATCH, ...
          headers => $request->{headers},  # hash reference
          id      => $request->{id},       # id of the upload or undef/''
          body    => $request->{body},     # better as a ref to a scalar
          cb_data => $something_for_callback,  # anything more you need
       );
       # The $response is-a Protocol::Tus::Response
    
       # or you can decide to call the relevant methods directly. 
       $response = $tus->HTTP_HEAD($request->@{qw< headers id>});
       $response = $tus->HTTP_OPTIONS;
       $response = $tus->HTTP_PATCH($request->@{qw< headers id body >});
       $response = $tus->HTTP_POST($request->@{qw< headers body >}, $cb_data);
       $response = $tus->HTTP_DELETE($request->{headers}, $request->{id});
       # Again, the $response is-a Protocol::Tus::Response

DESCRIPTION

    Implement handling for the Tus protocol in Perl.

 Usage Overview

    The constructor requires psasing a model, either as an instance or with
    a specification useful for creating an instance:

       my $tus = Protocol::Tus->new(
          model => {
             class => 'Protocol::Tus::LocalDir',
             args  => { root => '/path/to/somewhere' },
          },
          generate_location => sub (%args) { ... },  # optional
          on_create => sub (%args) { ... },     # optional
          on_complete => sub (%args) { ... },   # optional
       );

    The model can be retrieved through the model accessor. It SHOULD be an
    instance of a class derived from Protocol::Tus::AbstractModel and it
    sure MUST implement its whole interface.

    The main method is HTTP_request, which accepts data gathered from an
    input request and figures out the best way to address it. This is the
    suggested way of using the module, because the Tus specification
    requires honoring the X-HTTP-Method-Override header before any action
    is done.

    Ancillary methods for addressing each specific request method are
    available too.

 Example Usage in Mojolicious

    A possible usage in a Mojolicious application might start from defining
    the base path for the endpoint and how to represent the different
    uploads; one possible way is in the example below (note: untested):

       use v5.24;
       use warnings;
       use Mojolicious::Lite -signatures;
       use Protocol::Tus;
       use Ouch qw< bleep >;
    
       # /tus is the endpoint for creating new uploads or getting general
       # info about the API, while /tus/:id is to interact with one upload.
       # Both are folded onto the same callback that will provide a wrapper
       # around Protocol::Tus->HTTP_request.
       any '/tus'     => \&call_tus;
       any '/tus/:id' => \&call_tus;
    
       app->start;
    
       sub call_tus ($c) {
          my $tus = Protocol::Tus->new(
             model => {
                class => 'Protocol::Tus::LocalDir',
                args  => { root => '/path/to/storage' },
             },
          );
    
          my $request = $c->req;
          my $body = $request->body;
          my $tus_response = $tus->HTTP_request(
             $request->method,
             $request->headers->to_hash,
             $c->param('id'), # possibly undefined, it's OK
             \$body,
             cb_data => sub ($id) { $c->url_for("/tus-upload/$id") },
          );
    
          # log any exception. It's a Ouch object, so you might want to
          # take a look into $exception->data too.
          if (defined(my $exception = $tus_response->exception)) {
             $c->app->log->error(bleep($exception));
             $c->app->log->error($exception->data)
                if eval { $exception->isa('Ouch') };
          }
    
          # prepare the response to the client
          my $response = $c->res;
    
          # transfer headers from the $tus_response
          my $res_headers = $c->res->headers;
          my $tus_headers = $tus_response->headers; # hash ref
          $res_headers->header($_ => $tus_headers->{$_})
             for keys($tus_headers->%*);
    
          # rendering depends on the status code
          my $code = $tus_response->code;
          my $body = $tus_response->body;
          $c->render(status => $code, text => $text);
    
          return;
       }

INTERFACE

    The interface is designed to work in a framework-agnostic way, provided
    that methods are fed with the correct inputs, which in general are:

    HTTP method

      the HTTP method that was used to send the request. It's a string
      containing the HTTP method name, case insensitive (it will be turned
      into a uppercase string).

    headers

      a reference to a hash holding the request headers. It is assumed that
      keys are unique in a case-insensitive way, i.e. there are no two keys
      of interest (as per the Tus specification) that fold onto the same
      lowercase representation; apart from that, the keys can have whatever
      case in line with the HTTP specification.

    id

      the identifier of an upload that the API is supposed to operate on.
      The Tus specification does not dictate any specific path or query
      structure and this module follows this pattern, it's up to the caller
      to figure out the right *upload identifier* for a request, if any.

    body

      the body of a request, e.g. in a PATCH or POST interaction. As the
      data might be relevant and best not copied too much around, it's
      possible and suggested to pass a reference to the scalar value that
      holds the data.

    Each method receives the arguments that it needs either as a key/value
    pairs list or as a positional argument list, as detailed below. Method
    starting with HTTP_ return an instance of Protocol::Tus::Response and
    never raise exceptions.

    You are encouraged to determine the structure of the identifier and, in
    case, make sure that it is consistent with the model adopted. As an
    example, when using Protocol::Tus::LocalDir, identifiers are generated
    by the model and are always valid directory names. In any case, it will
    be up to the caller of the different methods to figure out how to
    represent these identifiers in the external API and how to extract them
    from the requests coming from clients.

 generate_location

       my $coderef = $tus->generate_location;

    Accessor to the optional callback to turn an upload identifier into a
    Location header needed in the 201 response when creating a new upload.
    If not set, the caller is supposed to generate the Location header
    independently.

    See "new".

 new

       my $tus = Protocol::Tus->new(
          model => $spec_or_object,
          generate_location => $sub_reference_1,
          on_create    => $sub_reference_2,
          on_complete  => $sub_reference_3,
       );
       my $tus = Protocol::Tus->new(
          {
             model => $spec_or_object,
             generate_location => $sub_reference_1,
             on_create    => $sub_reference_2,
             on_complete  => $sub_reference_3,
          }
       );

    Create a new instance of a Protocol::Tus.

    The following keys are supported:

    model

      set the model object or the specification to instantiate one.
      Required parameter.

      If an object is passed, it's assumed to be already valid; otherwise,
      the $spec_of_object is supposed to be a hash reference with keys
      class and args to create one.

    on_complete

      set the callback to invoke when an upload is successfully completed.

      The return value is ignored.

    on_create

      set the callback to invoke when a new upload is successfully created.
      If you need to just set the Location header in the response (which
      you are required to do as per the protocol interface) you might want
      to look into "generate_location"; this method allows you to do
      fancier things with a more readable interface.

      The return value is ignored.

    generate_location

      set the callback to turn an identifier into a Location header when
      creating a new upload. The signature of this callback is as follows:

         my $location = $callback->(%args);

      The return value MUST be a value suitable for a Location header in
      the response.

    The three callbacks are invoked as follows:

       $callback->(%args);

    The %args supports the following key/value pairs:

    response

      the Protocol::Tus::Response currently candidate as a return value
      from the invoked method;

    tus

      the Protocol::Tus object invoking the callback;

    upload

      the Protocol::Tus::Upload object triggering the event.

 model

       my $model = $tus->model;

    Accessor to the model object. Most probably it will be something
    derived from Protocol::Tus::AbstractModel, like
    Protocol::Tus::LocalDir.

 on_complete

       my $coderef = $tus->on_complete;

    Accessor to the optional callback invoked upon completion of an upload.

    See "new".

 on_create

       my $coderef = $tus->on_create;

    Accessor to the optional callback invoked upon creation of an upload.

    See "new".

 HTTP_request

       my $response = $tus->HTTP_request(%args);

    Handle an incoming request. Not all arguments will be used but they are
    required to provide a single entry point for the whole Tus interface.

    Supported arguments are method, headers, body, id, and cb_data.

  HTTP_HEAD

       my $response = $tus->HTTP_HEAD($headers, $id);

 HTTP_OPTIONS

       my $response = $tus->HTTP_OPTIONS;

 HTTP_PATCH

       my $response = $tus->HTTP_PATCH($headers, $id, $body);

 HTTP_POST

       my $response = $tus->HTTP_POST($headers, $body, $cb_data);

 HTTP_DELETE

       my $response = $tus->HTTP_DELETE($headers, $id);

BUGS AND LIMITATIONS

    Minimul perl version 5.24.

    Report bugs through Codeberg (patches welcome) at
    https://codeberg.org/polettix/Protocol-Tus.

AUTHOR

    Flavio Poletti <flavio@polettix.it>

COPYRIGHT AND LICENSE

    Copyright 2026 by Flavio Poletti <flavio@polettix.it>

    Licensed under the Apache License, Version 2.0 (the "License"); you may
    not use this file except in compliance with the License. You may obtain
    a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
    implied. See the License for the specific language governing
    permissions and limitations under the License.