NAME

Mojo::UserAgent::Mockable::Serializer - A class that serializes Mojo transactions created by Mojo::UserAgent::Mockable.

VERSION

version 1.56

SYNOPSIS

    # This module is not intended to be used directly. Synopsis here is given to show how 
    # Mojo::UserAgent::Mockable uses the module to record transactions.
    
    use Mojo::UserAgent::Mockable::Serializer;
    use Mojo::UserAgent;
    use File::Slurper qw(read_text write_text);

    my $ua = Mojo::UserAgent->new;
    my $serializer = Mojo::UserAgent::Mockable::Serializer->new;
    
    my @transactions;
    push @transactions, $ua->get('http://example.com');
    push @transactions, $ua->get('http://example.com/object/123');
    push @transactions, $ua->get('http://example.com/subobject/456');

    my $json = $serializer->serialize(@transactions);
    write_text('/path/to/file/json', $json);

    # OR

    $serializer->store('/path/to/file.json', @transactions);

    # Later...

    my $json = read_text('/path/to/file.json');
    my @reconstituted_transactions = $serializer->deserialize($json);

    # OR
    #
    my @reconstituted_transactions = Mojo::UserAgent::Mockable::Serializer->retrieve('/path/to/file.json');

METHODS

serialize

Serialize or freeze one or more instances of Mojo::Transaction. Takes an array of transactions to be serialized as the single argument. This method will generate a warning if the instance has any subscribers (see "on" in Mojo::EventEmitter). Suppress this warning with (e.g.):

  no warnings 'Mojo::UserAgent::Mock::Serializer';
  $serializer->serialize(@transactions);
  use warnings 'Mojo::UserAgent::Mock::Serializer';

deserialize

Deserialize or thaw a previously serialized array of Mojo:Transaction. Arguments:

$data

JSON containing the serialized objects.

store

Serialize an instance of Mojo::Transaction and write it to the given file or file handle. Takes two arguments:

$file

File or handle to write serialized object to.

@transactions

Array of Mojo::Transaction to serialize

retrieve

Read from the specified file or file handle and deserialize one or more instances of Mojo::Transaction from the data read. If a file handle is passed, data will be read until an EOF is received. Arguments:

$file

File containing serialized object

EVENTS

This module emits the following events:

pre_thaw

    $serializer->on( pre_thaw => sub {
        my ($serializer, $slush) = @_;
        ...
    });

Emitted immediately before transactions are deserialized. See "DATA STRUCTURE" below for details of the format of $slush.

post_thaw

    # Note that $transactions is an arrayref here.
    $serializer->on( post_thaw => sub {
        my ($serializer, $transactions, $slush) = @_;
        ...
    }

Emitted immediately after transactions are deserialized. See "DATA STRUCTURE" below for details of the format of $slush.

In addition, each transaction, as well as each message therein, serialized using this module will emit the following events:

pre_freeze

    $transaction->on(freeze => sub {
        my $tx = shift;
        ...
    });

Emitted immediately before the transaction is serialized.

post_freeze

Emitted immediately after the transaction is serialized. See "Messages" for details of the frozen format.

    $transaction->on(post_freeze => sub {
        my $tx = shift;
        my $frozen = shift;
        ...
    });

DATA STRUCTURE

serialize produces, and deserialize expects, JSON data. Transactions are stored as an array of JSON objects (i.e. hashes). Each transaction object has the keys:

'class'

The original class of the transaction.

'request'

The request portion of the transaction (e.g. "GET /foo/bar ..."). See "Messages" below for encoding details.

'response'

The response portion of the transaction (e.g. "200 OK ..."). See "Messages" below for encoding details.

Messages

Individual messages are stored as JSON objects (i.e. hashes) with the keys:

'class'

The class name of the serialized object. This should be a subclass of Mojo::Message

'events'

Array of events with subscribers in the serialized object. These events will be re-emitted after the "thaw" event is emitted, but any subscribers present in the original object will be lost.

'body'

The raw HTTP message body.

CAVEATS

This module does not serialize any event listeners. This is unlikely to change in future releases.

AUTHOR

Kit Peters <popefelix@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Kit Peters.

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

cpanm Mojo::UserAgent::Mockable

perl -MCPAN -e shell
install Mojo::UserAgent::Mockable