=head1 NAME

Dancer2::Session::Etcd - Etcd session engine for Dancer2

=head1 VERSION

0.001

=head1 DESCRIPTION

DEVELOPMENT ONLY

This module implements a session engine for Dancer2 by serializing the session, and storing it in a database via Etcd.

JSON was chosen as the default serialization format, as it is fast, terse, and portable.

=head1 SYNOPSIS

Example configuration:

session: "Etcd"
engines:
  session:
    Etcd:
      dsn:      "host=127.0.0.1;port=3306"
      schema_class:    "Interchange6::Schema"  # Etcd3 schema
      user:     "user"      # Username used to connect to the database
      password: "password"  # Password to connect to the database
      resultset: "MySession" # Etcd3 resultset, defaults to Session
      id_key: "my_session_id" # defaults to sessions_id
      data_key: "my_session_data" # defaults to session_data
      serializer: "YAML"    # defaults to JSON

=head1 SESSION EXPIRATION

A timestamp field that updates when a session is updated is recommended, so you can expire sessions server-side as well as client-side.

This session engine will not automagically remove expired sessions on the server, but with a timestamp field as above, you should be able to to do this manually.

=head1 ATTRIBUTES

=head2 schema_class

Etcd3 schema class, e.g. L.

=head2 db_connection_name

The L database connection name.

If this option is provided then L, L, L and L are all ignored.

=head2 resultset

Etcd3 resultset, defaults to C.

=head2 id_column

Column for session id, defaults to C.

If this column is not the primary key of the table, it should have a unique constraint added to it. See L<Etcd3::ResultSource/add_unique_constraint>.

=head2 data_column

Column for session data, defaults to C.

=head2 dsn

L dsn to connect to the database.

=head2 user

Database username.

=head2 password

Database password.

=head2 schema

L schema.

=head2 serializer

Serializer to use, defaults to JSON.

L provides the following serializer classes:

=over

=item JSON - L

=item Sereal - L

=item YAML - L

=back

If you do not use the default JSON serializer then you might need to install additional modules - see the specific serializer class for details.

You can also use your own serializer class by passing the fully-qualified class name as argument to this option, e.g.: MyApp::Session::Serializer

=head2 serializer_object

Vivified L object.

=head2 serialize_options

Options to be passed to the constructor of the the C class as a hash reference.

=head2 deserialize_options

Options to be passed to the constructor of the the C class as a hash reference.

=head1 METHODS

=head2 _flush

Write the session to the database. Returns the session object.

=head2 _retrieve($id)

Look for a session with the given id.

Returns the session object if found, C if not. Dies if the session was found, but could not be deserialized.

=head2 _change_id( $old_id, $new_id )

Change ID of session with C<$old_id> to <$new_id>.

=head2 _destroy()

Remove the current session object from the database.

=head1 SEE ALSO

L, L

=head1 AUTHOR

Sam Batschelet (hexfusion) <sbatschelet mac.com>

=head1 ACKNOWLEDGEMENTS

Based on code from L written by James Aitken and code from L written by Naveed Massjouni. and code from L written by Stefan Hornberg.

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) Sam Batschelet.

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