README.md
1[![Build Status](https://travis-ci.org/tokuhirom/HTTP-Session2.png?branch=master)](https://travis-ci.org/tokuhirom/HTTP-Session2) [![Coverage Status](https://coveralls.io/repos/tokuhirom/HTTP-Session2/badge.png?branch=master)](https://coveralls.io/r/tokuhirom/HTTP-Session2?branch=master)
2# NAME
3
4HTTP::Session2 - HTTP session management
5
6# SYNOPSIS
7
8 package MyApp;
9 use HTTP::Session2;
10
11 my $cipher = Crypt::CBC->new(
12 {
13 key => 'abcdefghijklmnop',
14 cipher => 'Rijndael',
15 }
16 );
17 sub session {
18 my $self = shift;
19 if (!exists $self->{session}) {
20 $self->{session} = HTTP::Session2::ClientStore2->new(
21 env => $env,
22 secret => 'very long secret string'
23 cipher => $cipher,
24 );
25 }
26 $self->{session};
27 }
28
29 __PACKAGE__->add_trigger(
30 AFTER_DISPATCH => sub {
31 my ($c, $res) = @_;
32 if ($c->{session}) {
33 $c->{session}->finalize_plack_response($res);
34 }
35 },
36 );
37
38# DESCRIPTION
39
40HTTP::Session2 is yet another HTTP session data management library.
41
42# RELEASE STATE
43
44Alpha. Any API will change without notice.
45
46# MOTIVATION
47
48We need a thrifty session management library.
49
50# What's different from HTTP::Session 1?
51
52## Generate XSRF protection token by session management library
53
54Most of web application needs XSRF protection library.
55
56tokuhirom guess XSRF token is closely related with session management.
57
58## Dropped StickyQuery support
59
60In Japan, old DoCoMo's phone does not support cookie.
61Then, we need to support query parameter based session management.
62
63But today, Japanese people are using smart phone :)
64We don't have to support legacy phones on new project.
65
66# Automatic XSRF token sending.
67
68This is an example code for filling XSRF token.
69This code requires jQuery.
70
71 $(function () {
72 "use strict";
73
74 var xsrf_token = getXSRFToken();
75 $("form").each(function () {
76 var form = $(this);
77 var method = form.attr('method');
78 if (method === 'get' || method === 'GET') {
79 return;
80 }
81
82 var input = $(document.createElement('input'));
83 input.attr('type', 'hidden');
84 input.attr('name', 'XSRF-TOKEN');
85 input.attr('value', xsrf_token);
86 form.prepend(input);
87 });
88
89 function getXSRFToken() {
90 var cookies = document.cookie.split(/\s*;\s*/);
91 for (var i=0,l=cookies.length; i<l; i++) {
92 var matched = cookies[i].match(/^XSRF-TOKEN=(.*)$/);
93 if (matched) {
94 return matched[1];
95 }
96 }
97 return undefined;
98 }
99 });
100
101# Validate XSRF token in your application
102
103You need to call XSRF validator.
104
105 __PACKAGE__->add_trigger(
106 BEFORE_DISPATCH => sub {
107 my $c = shift;
108 my $req = $c->req;
109
110 if ($req->method ne 'GET' && $req->method ne 'HEAD') {
111 my $xsrf_token = $req->header('X-XSRF-TOKEN') || $req->param('xsrf-token');
112 unless ($session->validate_xsrf_token($xsrf_token)) {
113 return [
114 403,
115 [],
116 ['XSRF detected'],
117 ];
118 }
119 }
120 return;
121 }
122 );
123
124# pros/cons for ServerStore/ClientStore2
125
126## ServerStore
127
128### pros
129
130- It was used well.
131- User can't see anything.
132- You can store large data in session.
133
134### cons
135
136- Setup is hard.
137
138 You need to setup some configuration for your application.
139
140## ClientStore2
141
142### pros
143
144- You don't need to store anything on your server
145
146 It makes easy to setup your server environment.
147
148- Less server side disk
149
150 It helps your wallet.
151
152### cons
153
154- Security
155
156 I hope this module is secure. Because the data was signed by HMAC. But security thing is hard.
157
158- Bandwidth
159
160 If you store the large data to the session, your session data is send to the server per every request.
161 It may hits band-width issue. If you are writing high traffic web site, you should use server side store.
162
163- Capacity
164
165 Cookies are usually limited to 4096 bytes. You can't store large data to the session.
166 You should care the cookie size, or checking cookie size by the Plack::Middleware layer.
167
168 Ref. [RFC2965](http://tools.ietf.org/html/rfc2965)
169
170# FAQ
171
172- How can I implement "Keep me signed in" checkbox?
173
174 You can implement it like following:
175
176 sub dispatch_login {
177 my $c = shift;
178 if ($c->request->parameters->{'keep_me_signed_in'}) {
179 $c->session->session_cookie->{expires} = '+1M';
180 }
181 $c->session->regenerate_id();
182 my $user = User->login($c->request->parameters);
183 $c->session->set('user_id' => $user->id);
184 }
185
186# LICENSE
187
188Copyright (C) tokuhirom.
189
190This library is free software; you can redistribute it and/or modify
191it under the same terms as Perl itself.
192
193# AUTHOR
194
195tokuhirom <tokuhirom@gmail.com>
196
197# CONTRIBUTORS
198
199magai
200