`Zaphod::Session->new ARGS`

Creates a new session.

The following fields can be set through the constructor:

    clients  - hashref of preexisting clients
    document - arrayref of the document
    timeout  - client session timeout in seconds
    cookie   - the secret cookie
    name     - the session name

`$session->log TYPE, MSG`

Logging callback. Currently just prints to STDOUT

`$session->api API`

Factory method to produce and instantiate the APIs. Currently, the only supported API is

`$session->action_from_client CLIENT,STATE,ACTIONS`

Insert actions from a client, advancing the master state.

Returns a true value if all actions applied without problems. If there were some actions that couldn't be merged without a conflict, returns a false value. All other actions got applied.

The conflicting action is silently discarded at the moment, at least there's no feedback mechanism for the client yet.

`$session->actions_for_client CLIENT, STATE`

Returns the actions that bring the client from its current state to the current state of the master.

`$session->gen_cookie CLIENT`

Generates a shared secret for identifying a connected client.

`$session->valid_cookie COOKIE`

Returns true if the given cookie is a valid client connection. In fact, the value returned is the hash entry for the relevant client.

`$session->connect_client VISUAL`

Adds/connects a new client.

The current client attributes are

  state           - state of the client document
  last_seen       - epoch when the client last connected
  cursor_position - offset of the client position
  visual          - the name of the client

The function returns the handle to be used in all future function calls of the client.

`$session->sane_username VISUAL`

Returns true if the username VISUAL is considered sane enough.

Currently this means it doesn't start with, end with or contain multiple whitespace characters.

HTML entities are not yet handled (see TODO)

`$session->unique_username VISUAL`

Returns true if the username VISUAL is considered unique enough.

`$session->saw_client CLIENT`

Resets the timeout counter for CLIENT if it exits. Returns the hashref corresponding to CLIENT if it exists.

`$session->client_cursor CLIENT, OFFSET`

Sets the offset for the cursor position of the client

`$session->disconnect_client CLIENT`

Removes the client from the session

`$session->prune_clients TIMEOUT`

Disconnects all clients that haven't polled since TIMEOUT seconds. If TIMEOUT is not given, the value of the timeout accessor is used.

If a disconnected client later connects again, the connection is rejected and the client will have to log in again.

`$session->users_for_client CLIENT`

Returns the list of the other users and their positions for the session

`$session->set_name NEWNAME`

Sets the name of the current session, permissions provided.

The new name will be broadcast to the other clients. The name change is currently out-of-band with the editor, so there is no undo/redo functionality for it.

Serializes the session to disk. This will create two files in DIR, $session.document and $session.meta. The .document file will contain the document, and .meta file will contain metadata. The following metadata is saved:

    state
    cookie
    secret
    name

If more elaborate session management comes to frutition, also the session owner and allowed viewers etc. will be saved in the .meta file. The .meta file is a simple custom file format of key-value pairs matching

  /^(\w+)=(.*)$/

and will be read and written as UTF-8. The document will be read and written via :utf8 as well.

`Zaphod::Session->load FILE, ARGS`

Constructor to intialize and then load a session from a file.

The filename can be either the name of the document file or the name of the metafile.

Currently, persistent_values is not checked against the keys loaded from the .meta file.

`$session->persistent_values`

(Class method)

Returns all keys except document that persist on-disk.

AUTHOR

Written by Max Maischein <corion@cpan.org>

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