ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Handle.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.134 by root, Fri Jul 3 00:09:04 2009 UTC vs.
Revision 1.154 by root, Sat Jul 18 05:19:09 2009 UTC

1package AnyEvent::Handle; 1package AnyEvent::Handle;
2 2
3no warnings;
4use strict qw(subs vars);
5
6use AnyEvent ();
7use AnyEvent::Util qw(WSAEWOULDBLOCK);
8use Scalar::Util (); 3use Scalar::Util ();
9use Carp (); 4use Carp ();
10use Fcntl ();
11use Errno qw(EAGAIN EINTR); 5use Errno qw(EAGAIN EINTR);
12 6
7use AnyEvent (); BEGIN { AnyEvent::common_sense }
8use AnyEvent::Util qw(WSAEWOULDBLOCK);
9
13=head1 NAME 10=head1 NAME
14 11
15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 12AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16 13
17=cut 14=cut
18 15
19our $VERSION = 4.45; 16our $VERSION = 4.85;
20 17
21=head1 SYNOPSIS 18=head1 SYNOPSIS
22 19
23 use AnyEvent; 20 use AnyEvent;
24 use AnyEvent::Handle; 21 use AnyEvent::Handle;
25 22
26 my $cv = AnyEvent->condvar; 23 my $cv = AnyEvent->condvar;
27 24
28 my $handle = 25 my $hdl; $hdl = new AnyEvent::Handle
29 AnyEvent::Handle->new (
30 fh => \*STDIN, 26 fh => \*STDIN,
31 on_eof => sub { 27 on_error => sub {
28 my ($hdl, $fatal, $msg) = @_;
29 warn "got error $msg\n";
30 $hdl->destroy;
32 $cv->send; 31 $cv->send;
33 },
34 ); 32 );
35 33
36 # send some request line 34 # send some request line
37 $handle->push_write ("getinfo\015\012"); 35 $hdl->push_write ("getinfo\015\012");
38 36
39 # read the response line 37 # read the response line
40 $handle->push_read (line => sub { 38 $hdl->push_read (line => sub {
41 my ($handle, $line) = @_; 39 my ($hdl, $line) = @_;
42 warn "read line <$line>\n"; 40 warn "got line <$line>\n";
43 $cv->send; 41 $cv->send;
44 }); 42 });
45 43
46 $cv->recv; 44 $cv->recv;
47 45
… …
81 79
82=item on_eof => $cb->($handle) 80=item on_eof => $cb->($handle)
83 81
84Set the callback to be called when an end-of-file condition is detected, 82Set the callback to be called when an end-of-file condition is detected,
85i.e. in the case of a socket, when the other side has closed the 83i.e. in the case of a socket, when the other side has closed the
86connection cleanly. 84connection cleanly, and there are no outstanding read requests in the
85queue (if there are read requests, then an EOF counts as an unexpected
86connection close and will be flagged as an error).
87 87
88For sockets, this just means that the other side has stopped sending data, 88For sockets, this just means that the other side has stopped sending data,
89you can still try to write data, and, in fact, one can return from the EOF 89you can still try to write data, and, in fact, one can return from the EOF
90callback and continue writing data, as only the read part has been shut 90callback and continue writing data, as only the read part has been shut
91down. 91down.
92 92
93While not mandatory, it is I<highly> recommended to set an EOF callback,
94otherwise you might end up with a closed socket while you are still
95waiting for data.
96
97If an EOF condition has been detected but no C<on_eof> callback has been 93If an EOF condition has been detected but no C<on_eof> callback has been
98set, then a fatal error will be raised with C<$!> set to <0>. 94set, then a fatal error will be raised with C<$!> set to <0>.
99 95
100=item on_error => $cb->($handle, $fatal, $message) 96=item on_error => $cb->($handle, $fatal, $message)
101 97
102This is the error callback, which is called when, well, some error 98This is the error callback, which is called when, well, some error
103occured, such as not being able to resolve the hostname, failure to 99occured, such as not being able to resolve the hostname, failure to
104connect or a read error. 100connect or a read error.
105 101
106Some errors are fatal (which is indicated by C<$fatal> being true). On 102Some errors are fatal (which is indicated by C<$fatal> being true). On
107fatal errors the handle object will be shut down and will not be usable 103fatal errors the handle object will be destroyed (by a call to C<< ->
108(but you are free to look at the current C<< ->rbuf >>). Examples of fatal 104destroy >>) after invoking the error callback (which means you are free to
109errors are an EOF condition with active (but unsatisifable) read watchers 105examine the handle object). Examples of fatal errors are an EOF condition
110(C<EPIPE>) or I/O errors. 106with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors.
111 107
112AnyEvent::Handle tries to find an appropriate error code for you to check 108AnyEvent::Handle tries to find an appropriate error code for you to check
113against, but in some cases (TLS errors), this does not work well. It is 109against, but in some cases (TLS errors), this does not work well. It is
114recommended to always output the C<$message> argument in human-readable 110recommended to always output the C<$message> argument in human-readable
115error messages (it's usually the same as C<"$!">). 111error messages (it's usually the same as C<"$!">).
… …
133and no read request is in the queue (unlike read queue callbacks, this 129and no read request is in the queue (unlike read queue callbacks, this
134callback will only be called when at least one octet of data is in the 130callback will only be called when at least one octet of data is in the
135read buffer). 131read buffer).
136 132
137To access (and remove data from) the read buffer, use the C<< ->rbuf >> 133To access (and remove data from) the read buffer, use the C<< ->rbuf >>
138method or access the C<$handle->{rbuf}> member directly. Note that you 134method or access the C<< $handle->{rbuf} >> member directly. Note that you
139must not enlarge or modify the read buffer, you can only remove data at 135must not enlarge or modify the read buffer, you can only remove data at
140the beginning from it. 136the beginning from it.
141 137
142When an EOF condition is detected then AnyEvent::Handle will first try to 138When an EOF condition is detected then AnyEvent::Handle will first try to
143feed all the remaining data to the queued callbacks and C<on_read> before 139feed all the remaining data to the queued callbacks and C<on_read> before
144calling the C<on_eof> callback. If no progress can be made, then a fatal 140calling the C<on_eof> callback. If no progress can be made, then a fatal
145error will be raised (with C<$!> set to C<EPIPE>). 141error will be raised (with C<$!> set to C<EPIPE>).
142
143Note that, unlike requests in the read queue, an C<on_read> callback
144doesn't mean you I<require> some data: if there is an EOF and there
145are outstanding read requests then an error will be flagged. With an
146C<on_read> callback, the C<on_eof> callback will be invoked.
146 147
147=item on_drain => $cb->($handle) 148=item on_drain => $cb->($handle)
148 149
149This sets the callback that is called when the write buffer becomes empty 150This sets the callback that is called when the write buffer becomes empty
150(or when the callback is set and the buffer is empty already). 151(or when the callback is set and the buffer is empty already).
… …
249 250
250A string used to identify the remote site - usually the DNS hostname 251A string used to identify the remote site - usually the DNS hostname
251(I<not> IDN!) used to create the connection, rarely the IP address. 252(I<not> IDN!) used to create the connection, rarely the IP address.
252 253
253Apart from being useful in error messages, this string is also used in TLS 254Apart from being useful in error messages, this string is also used in TLS
254common name verification (see C<verify_cn> in L<AnyEvent::TLS>). 255peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This
256verification will be skipped when C<peername> is not specified or
257C<undef>.
255 258
256=item tls => "accept" | "connect" | Net::SSLeay::SSL object 259=item tls => "accept" | "connect" | Net::SSLeay::SSL object
257 260
258When this parameter is given, it enables TLS (SSL) mode, that means 261When this parameter is given, it enables TLS (SSL) mode, that means
259AnyEvent will start a TLS handshake as soon as the conenction has been 262AnyEvent will start a TLS handshake as soon as the conenction has been
… …
296 299
297Instead of an object, you can also specify a hash reference with C<< key 300Instead of an object, you can also specify a hash reference with C<< key
298=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a 301=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
299new TLS context object. 302new TLS context object.
300 303
304=item on_starttls => $cb->($handle, $success[, $error_message])
305
306This callback will be invoked when the TLS/SSL handshake has finished. If
307C<$success> is true, then the TLS handshake succeeded, otherwise it failed
308(C<on_stoptls> will not be called in this case).
309
310The session in C<< $handle->{tls} >> can still be examined in this
311callback, even when the handshake was not successful.
312
313TLS handshake failures will not cause C<on_error> to be invoked when this
314callback is in effect, instead, the error message will be passed to C<on_starttls>.
315
316Without this callback, handshake failures lead to C<on_error> being
317called, as normal.
318
319Note that you cannot call C<starttls> right again in this callback. If you
320need to do that, start an zero-second timer instead whose callback can
321then call C<< ->starttls >> again.
322
323=item on_stoptls => $cb->($handle)
324
325When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
326set, then it will be invoked after freeing the TLS session. If it is not,
327then a TLS shutdown condition will be treated like a normal EOF condition
328on the handle.
329
330The session in C<< $handle->{tls} >> can still be examined in this
331callback.
332
333This callback will only be called on TLS shutdowns, not when the
334underlying handle signals EOF.
335
301=item json => JSON or JSON::XS object 336=item json => JSON or JSON::XS object
302 337
303This is the json coder object used by the C<json> read and write types. 338This is the json coder object used by the C<json> read and write types.
304 339
305If you don't supply it, then AnyEvent::Handle will create and use a 340If you don't supply it, then AnyEvent::Handle will create and use a
… …
327 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay}; 362 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
328 363
329 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}) 364 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
330 if $self->{tls}; 365 if $self->{tls};
331 366
332 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain}; 367 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
333 368
334 $self->start_read 369 $self->start_read
335 if $self->{on_read}; 370 if $self->{on_read};
336 371
337 $self->{fh} && $self 372 $self->{fh} && $self
338} 373}
339 374
340sub _shutdown { 375#sub _shutdown {
341 my ($self) = @_; 376# my ($self) = @_;
342 377#
343 delete @$self{qw(_tw _rw _ww fh wbuf on_read _queue)}; 378# delete @$self{qw(_tw _rw _ww fh wbuf on_read _queue)};
344 $self->{_eof} = 1; # tell starttls et. al to stop trying 379# $self->{_eof} = 1; # tell starttls et. al to stop trying
345 380#
346 &_freetls; 381# &_freetls;
347} 382#}
348 383
349sub _error { 384sub _error {
350 my ($self, $errno, $fatal, $message) = @_; 385 my ($self, $errno, $fatal, $message) = @_;
351 386
352 $self->_shutdown
353 if $fatal;
354
355 $! = $errno; 387 $! = $errno;
356 $message ||= "$!"; 388 $message ||= "$!";
357 389
358 if ($self->{on_error}) { 390 if ($self->{on_error}) {
359 $self->{on_error}($self, $fatal, $message); 391 $self->{on_error}($self, $fatal, $message);
392 $self->destroy if $fatal;
360 } elsif ($self->{fh}) { 393 } elsif ($self->{fh}) {
394 $self->destroy;
361 Carp::croak "AnyEvent::Handle uncaught error: $message"; 395 Carp::croak "AnyEvent::Handle uncaught error: $message";
362 } 396 }
363} 397}
364 398
365=item $fh = $handle->fh 399=item $fh = $handle->fh
… …
427 local $SIG{__DIE__}; 461 local $SIG{__DIE__};
428 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1]; 462 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
429 }; 463 };
430} 464}
431 465
466=item $handle->on_starttls ($cb)
467
468Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).
469
470=cut
471
472sub on_starttls {
473 $_[0]{on_starttls} = $_[1];
474}
475
476=item $handle->on_stoptls ($cb)
477
478Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
479
480=cut
481
482sub on_starttls {
483 $_[0]{on_stoptls} = $_[1];
484}
485
432############################################################################# 486#############################################################################
433 487
434=item $handle->timeout ($seconds) 488=item $handle->timeout ($seconds)
435 489
436Configures (or disables) the inactivity timeout. 490Configures (or disables) the inactivity timeout.
… …
460 $self->{_activity} = $NOW; 514 $self->{_activity} = $NOW;
461 515
462 if ($self->{on_timeout}) { 516 if ($self->{on_timeout}) {
463 $self->{on_timeout}($self); 517 $self->{on_timeout}($self);
464 } else { 518 } else {
465 $self->_error (&Errno::ETIMEDOUT); 519 $self->_error (Errno::ETIMEDOUT);
466 } 520 }
467 521
468 # callback could have changed timeout value, optimise 522 # callback could have changed timeout value, optimise
469 return unless $self->{timeout}; 523 return unless $self->{timeout};
470 524
… …
533 Scalar::Util::weaken $self; 587 Scalar::Util::weaken $self;
534 588
535 my $cb = sub { 589 my $cb = sub {
536 my $len = syswrite $self->{fh}, $self->{wbuf}; 590 my $len = syswrite $self->{fh}, $self->{wbuf};
537 591
538 if ($len >= 0) { 592 if (defined $len) {
539 substr $self->{wbuf}, 0, $len, ""; 593 substr $self->{wbuf}, 0, $len, "";
540 594
541 $self->{_activity} = AnyEvent->now; 595 $self->{_activity} = AnyEvent->now;
542 596
543 $self->{on_drain}($self) 597 $self->{on_drain}($self)
… …
683 737
684=item $handle->push_shutdown 738=item $handle->push_shutdown
685 739
686Sometimes you know you want to close the socket after writing your data 740Sometimes you know you want to close the socket after writing your data
687before it was actually written. One way to do that is to replace your 741before it was actually written. One way to do that is to replace your
688C<on_drain> handler by a callback that shuts down the socket. This method 742C<on_drain> handler by a callback that shuts down the socket (and set
689is a shorthand for just that, and replaces the C<on_drain> callback with: 743C<low_water_mark> to C<0>). This method is a shorthand for just that, and
744replaces the C<on_drain> callback with:
690 745
691 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 746 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown
692 747
693This simply shuts down the write side and signals an EOF condition to the 748This simply shuts down the write side and signals an EOF condition to the
694the peer. 749the peer.
… …
697afterwards. This is the cleanest way to close a connection. 752afterwards. This is the cleanest way to close a connection.
698 753
699=cut 754=cut
700 755
701sub push_shutdown { 756sub push_shutdown {
757 my ($self) = @_;
758
759 delete $self->{low_water_mark};
702 $_[0]->{on_drain} = sub { shutdown $_[0]{fh}, 1 }; 760 $self->on_drain (sub { shutdown $_[0]{fh}, 1 });
703} 761}
704 762
705=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 763=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
706 764
707This function (not method) lets you add your own types to C<push_write>. 765This function (not method) lets you add your own types to C<push_write>.
… …
808 866
809 if ( 867 if (
810 defined $self->{rbuf_max} 868 defined $self->{rbuf_max}
811 && $self->{rbuf_max} < length $self->{rbuf} 869 && $self->{rbuf_max} < length $self->{rbuf}
812 ) { 870 ) {
813 $self->_error (&Errno::ENOSPC, 1), return; 871 $self->_error (Errno::ENOSPC, 1), return;
814 } 872 }
815 873
816 while () { 874 while () {
817 # we need to use a separate tls read buffer, as we must not receive data while 875 # we need to use a separate tls read buffer, as we must not receive data while
818 # we are draining the buffer, and this can only happen with TLS. 876 # we are draining the buffer, and this can only happen with TLS.
… …
822 880
823 if (my $cb = shift @{ $self->{_queue} }) { 881 if (my $cb = shift @{ $self->{_queue} }) {
824 unless ($cb->($self)) { 882 unless ($cb->($self)) {
825 if ($self->{_eof}) { 883 if ($self->{_eof}) {
826 # no progress can be made (not enough data and no data forthcoming) 884 # no progress can be made (not enough data and no data forthcoming)
827 $self->_error (&Errno::EPIPE, 1), return; 885 $self->_error (Errno::EPIPE, 1), return;
828 } 886 }
829 887
830 unshift @{ $self->{_queue} }, $cb; 888 unshift @{ $self->{_queue} }, $cb;
831 last; 889 last;
832 } 890 }
… …
840 && !@{ $self->{_queue} } # and the queue is still empty 898 && !@{ $self->{_queue} } # and the queue is still empty
841 && $self->{on_read} # but we still have on_read 899 && $self->{on_read} # but we still have on_read
842 ) { 900 ) {
843 # no further data will arrive 901 # no further data will arrive
844 # so no progress can be made 902 # so no progress can be made
845 $self->_error (&Errno::EPIPE, 1), return 903 $self->_error (Errno::EPIPE, 1), return
846 if $self->{_eof}; 904 if $self->{_eof};
847 905
848 last; # more data might arrive 906 last; # more data might arrive
849 } 907 }
850 } else { 908 } else {
… …
856 914
857 if ($self->{_eof}) { 915 if ($self->{_eof}) {
858 if ($self->{on_eof}) { 916 if ($self->{on_eof}) {
859 $self->{on_eof}($self) 917 $self->{on_eof}($self)
860 } else { 918 } else {
861 $self->_error (0, 1); 919 $self->_error (0, 1, "Unexpected end-of-file");
862 } 920 }
863 } 921 }
864 922
865 # may need to restart read watcher 923 # may need to restart read watcher
866 unless ($self->{_rw}) { 924 unless ($self->{_rw}) {
… …
1100 return 1; 1158 return 1;
1101 } 1159 }
1102 1160
1103 # reject 1161 # reject
1104 if ($reject && $$rbuf =~ $reject) { 1162 if ($reject && $$rbuf =~ $reject) {
1105 $self->_error (&Errno::EBADMSG); 1163 $self->_error (Errno::EBADMSG);
1106 } 1164 }
1107 1165
1108 # skip 1166 # skip
1109 if ($skip && $$rbuf =~ $skip) { 1167 if ($skip && $$rbuf =~ $skip) {
1110 $data .= substr $$rbuf, 0, $+[0], ""; 1168 $data .= substr $$rbuf, 0, $+[0], "";
… …
1126 my ($self, $cb) = @_; 1184 my ($self, $cb) = @_;
1127 1185
1128 sub { 1186 sub {
1129 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 1187 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1130 if ($_[0]{rbuf} =~ /[^0-9]/) { 1188 if ($_[0]{rbuf} =~ /[^0-9]/) {
1131 $self->_error (&Errno::EBADMSG); 1189 $self->_error (Errno::EBADMSG);
1132 } 1190 }
1133 return; 1191 return;
1134 } 1192 }
1135 1193
1136 my $len = $1; 1194 my $len = $1;
… …
1139 my $string = $_[1]; 1197 my $string = $_[1];
1140 $_[0]->unshift_read (chunk => 1, sub { 1198 $_[0]->unshift_read (chunk => 1, sub {
1141 if ($_[1] eq ",") { 1199 if ($_[1] eq ",") {
1142 $cb->($_[0], $string); 1200 $cb->($_[0], $string);
1143 } else { 1201 } else {
1144 $self->_error (&Errno::EBADMSG); 1202 $self->_error (Errno::EBADMSG);
1145 } 1203 }
1146 }); 1204 });
1147 }); 1205 });
1148 1206
1149 1 1207 1
… …
1216=cut 1274=cut
1217 1275
1218register_read_type json => sub { 1276register_read_type json => sub {
1219 my ($self, $cb) = @_; 1277 my ($self, $cb) = @_;
1220 1278
1221 require JSON; 1279 my $json = $self->{json} ||=
1280 eval { require JSON::XS; JSON::XS->new->utf8 }
1281 || do { require JSON; JSON->new->utf8 };
1222 1282
1223 my $data; 1283 my $data;
1224 my $rbuf = \$self->{rbuf}; 1284 my $rbuf = \$self->{rbuf};
1225
1226 my $json = $self->{json} ||= JSON->new->utf8;
1227 1285
1228 sub { 1286 sub {
1229 my $ref = eval { $json->incr_parse ($self->{rbuf}) }; 1287 my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1230 1288
1231 if ($ref) { 1289 if ($ref) {
… …
1239 $json->incr_skip; 1297 $json->incr_skip;
1240 1298
1241 $self->{rbuf} = $json->incr_text; 1299 $self->{rbuf} = $json->incr_text;
1242 $json->incr_text = ""; 1300 $json->incr_text = "";
1243 1301
1244 $self->_error (&Errno::EBADMSG); 1302 $self->_error (Errno::EBADMSG);
1245 1303
1246 () 1304 ()
1247 } else { 1305 } else {
1248 $self->{rbuf} = ""; 1306 $self->{rbuf} = "";
1249 1307
… …
1286 # read remaining chunk 1344 # read remaining chunk
1287 $_[0]->unshift_read (chunk => $len, sub { 1345 $_[0]->unshift_read (chunk => $len, sub {
1288 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1346 if (my $ref = eval { Storable::thaw ($_[1]) }) {
1289 $cb->($_[0], $ref); 1347 $cb->($_[0], $ref);
1290 } else { 1348 } else {
1291 $self->_error (&Errno::EBADMSG); 1349 $self->_error (Errno::EBADMSG);
1292 } 1350 }
1293 }); 1351 });
1294 } 1352 }
1295 1353
1296 1 1354 1
… …
1377 } 1435 }
1378} 1436}
1379 1437
1380our $ERROR_SYSCALL; 1438our $ERROR_SYSCALL;
1381our $ERROR_WANT_READ; 1439our $ERROR_WANT_READ;
1382our $ERROR_ZERO_RETURN;
1383 1440
1384sub _tls_error { 1441sub _tls_error {
1385 my ($self, $err) = @_; 1442 my ($self, $err) = @_;
1386 warn "$err,$!\n";#d#
1387 1443
1388 return $self->_error ($!, 1) 1444 return $self->_error ($!, 1)
1389 if $err == Net::SSLeay::ERROR_SYSCALL (); 1445 if $err == Net::SSLeay::ERROR_SYSCALL ();
1390 1446
1447 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1448
1449 # reduce error string to look less scary
1450 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1451
1452 if ($self->{_on_starttls}) {
1453 (delete $self->{_on_starttls})->($self, undef, $err);
1454 &_freetls;
1455 } else {
1456 &_freetls;
1391 $self->_error (&Errno::EPROTO, 1, 1457 $self->_error (Errno::EPROTO, 1, $err);
1392 Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ())); 1458 }
1393} 1459}
1394 1460
1395# poll the write BIO and send the data if applicable 1461# poll the write BIO and send the data if applicable
1396# also decode read data if possible 1462# also decode read data if possible
1397# this is basiclaly our TLS state machine 1463# this is basiclaly our TLS state machine
… …
1408 } 1474 }
1409 1475
1410 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp); 1476 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
1411 return $self->_tls_error ($tmp) 1477 return $self->_tls_error ($tmp)
1412 if $tmp != $ERROR_WANT_READ 1478 if $tmp != $ERROR_WANT_READ
1413 && ($tmp != $ERROR_SYSCALL || $!) 1479 && ($tmp != $ERROR_SYSCALL || $!);
1414 && $tmp != $ERROR_ZERO_RETURN;
1415 } 1480 }
1416 1481
1417 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) { 1482 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1418 unless (length $tmp) { 1483 unless (length $tmp) {
1419 # let's treat SSL-eof as we treat normal EOF 1484 $self->{_on_starttls}
1420 delete $self->{_rw}; 1485 and (delete $self->{_on_starttls})->($self, undef, "EOF during handshake"); # ???
1421 $self->{_eof} = 1;
1422 &_freetls; 1486 &_freetls;
1487
1488 if ($self->{on_stoptls}) {
1489 $self->{on_stoptls}($self);
1490 return;
1491 } else {
1492 # let's treat SSL-eof as we treat normal EOF
1493 delete $self->{_rw};
1494 $self->{_eof} = 1;
1495 }
1423 } 1496 }
1424 1497
1425 $self->{_tls_rbuf} .= $tmp; 1498 $self->{_tls_rbuf} .= $tmp;
1426 $self->_drain_rbuf unless $self->{_in_drain}; 1499 $self->_drain_rbuf unless $self->{_in_drain};
1427 $self->{tls} or return; # tls session might have gone away in callback 1500 $self->{tls} or return; # tls session might have gone away in callback
1428 } 1501 }
1429 1502
1430 $tmp = Net::SSLeay::get_error ($self->{tls}, -1); 1503 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1431 return $self->_tls_error ($tmp) 1504 return $self->_tls_error ($tmp)
1432 if $tmp != $ERROR_WANT_READ 1505 if $tmp != $ERROR_WANT_READ
1433 && ($tmp != $ERROR_SYSCALL || $!) 1506 && ($tmp != $ERROR_SYSCALL || $!);
1434 && $tmp != $ERROR_ZERO_RETURN;
1435 1507
1436 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) { 1508 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1437 $self->{wbuf} .= $tmp; 1509 $self->{wbuf} .= $tmp;
1438 $self->_drain_wbuf; 1510 $self->_drain_wbuf;
1439 } 1511 }
1512
1513 $self->{_on_starttls}
1514 and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
1515 and (delete $self->{_on_starttls})->($self, 1, "TLS/SSL connection established");
1440} 1516}
1441 1517
1442=item $handle->starttls ($tls[, $tls_ctx]) 1518=item $handle->starttls ($tls[, $tls_ctx])
1443 1519
1444Instead of starting TLS negotiation immediately when the AnyEvent::Handle 1520Instead of starting TLS negotiation immediately when the AnyEvent::Handle
… …
1461If it an error to start a TLS handshake more than once per 1537If it an error to start a TLS handshake more than once per
1462AnyEvent::Handle object (this is due to bugs in OpenSSL). 1538AnyEvent::Handle object (this is due to bugs in OpenSSL).
1463 1539
1464=cut 1540=cut
1465 1541
1542our %TLS_CACHE; #TODO not yet documented, should we?
1543
1466sub starttls { 1544sub starttls {
1467 my ($self, $ssl, $ctx) = @_; 1545 my ($self, $ssl, $ctx) = @_;
1468 1546
1469 require Net::SSLeay; 1547 require Net::SSLeay;
1470 1548
1471 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object" 1549 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1472 if $self->{tls}; 1550 if $self->{tls};
1473 1551
1474 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL (); 1552 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1475 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ (); 1553 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1476 $ERROR_ZERO_RETURN = Net::SSLeay::ERROR_ZERO_RETURN ();
1477 1554
1478 $ctx ||= $self->{tls_ctx}; 1555 $ctx ||= $self->{tls_ctx};
1479 1556
1480 if ("HASH" eq ref $ctx) { 1557 if ("HASH" eq ref $ctx) {
1481 require AnyEvent::TLS; 1558 require AnyEvent::TLS;
1482 1559
1483 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context 1560 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context
1561
1562 if ($ctx->{cache}) {
1563 my $key = $ctx+0;
1564 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1565 } else {
1484 $ctx = new AnyEvent::TLS %$ctx; 1566 $ctx = new AnyEvent::TLS %$ctx;
1567 }
1485 } 1568 }
1486 1569
1487 $self->{tls_ctx} = $ctx || TLS_CTX (); 1570 $self->{tls_ctx} = $ctx || TLS_CTX ();
1488 $self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername}); 1571 $self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername});
1489 1572
… …
1507 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1590 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1508 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1591 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1509 1592
1510 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio}); 1593 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1511 1594
1595 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1596 if $self->{on_starttls};
1597
1512 &_dotls; # need to trigger the initial handshake 1598 &_dotls; # need to trigger the initial handshake
1513 $self->start_read; # make sure we actually do read 1599 $self->start_read; # make sure we actually do read
1514} 1600}
1515 1601
1516=item $handle->stoptls 1602=item $handle->stoptls
… …
1528 if ($self->{tls}) { 1614 if ($self->{tls}) {
1529 Net::SSLeay::shutdown ($self->{tls}); 1615 Net::SSLeay::shutdown ($self->{tls});
1530 1616
1531 &_dotls; 1617 &_dotls;
1532 1618
1533 # we don't give a shit. no, we do, but we can't. no... 1619# # we don't give a shit. no, we do, but we can't. no...#d#
1534 # we, we... have to use openssl :/ 1620# # we, we... have to use openssl :/#d#
1535 &_freetls; 1621# &_freetls;#d#
1536 } 1622 }
1537} 1623}
1538 1624
1539sub _freetls { 1625sub _freetls {
1540 my ($self) = @_; 1626 my ($self) = @_;
1541 1627
1542 return unless $self->{tls}; 1628 return unless $self->{tls};
1543 1629
1544 $self->{tls_ctx}->_put_session (delete $self->{tls}); 1630 $self->{tls_ctx}->_put_session (delete $self->{tls});
1545 1631
1546 delete @$self{qw(_rbio _wbio _tls_wbuf)}; 1632 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1547} 1633}
1548 1634
1549sub DESTROY { 1635sub DESTROY {
1550 my ($self) = @_; 1636 my ($self) = @_;
1551 1637
… …
1575} 1661}
1576 1662
1577=item $handle->destroy 1663=item $handle->destroy
1578 1664
1579Shuts down the handle object as much as possible - this call ensures that 1665Shuts down the handle object as much as possible - this call ensures that
1580no further callbacks will be invoked and resources will be freed as much 1666no further callbacks will be invoked and as many resources as possible
1581as possible. You must not call any methods on the object afterwards. 1667will be freed. You must not call any methods on the object afterwards.
1582 1668
1583Normally, you can just "forget" any references to an AnyEvent::Handle 1669Normally, you can just "forget" any references to an AnyEvent::Handle
1584object and it will simply shut down. This works in fatal error and EOF 1670object and it will simply shut down. This works in fatal error and EOF
1585callbacks, as well as code outside. It does I<NOT> work in a read or write 1671callbacks, as well as code outside. It does I<NOT> work in a read or write
1586callback, so when you want to destroy the AnyEvent::Handle object from 1672callback, so when you want to destroy the AnyEvent::Handle object from
1587within such an callback. You I<MUST> call C<< ->destroy >> explicitly in 1673within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
1588that case. 1674that case.
1589 1675
1676Destroying the handle object in this way has the advantage that callbacks
1677will be removed as well, so if those are the only reference holders (as
1678is common), then one doesn't need to do anything special to break any
1679reference cycles.
1680
1590The handle might still linger in the background and write out remaining 1681The handle might still linger in the background and write out remaining
1591data, as specified by the C<linger> option, however. 1682data, as specified by the C<linger> option, however.
1592 1683
1593=cut 1684=cut
1594 1685
… …
1661 1752
1662 $handle->on_read (sub { }); 1753 $handle->on_read (sub { });
1663 $handle->on_eof (undef); 1754 $handle->on_eof (undef);
1664 $handle->on_error (sub { 1755 $handle->on_error (sub {
1665 my $data = delete $_[0]{rbuf}; 1756 my $data = delete $_[0]{rbuf};
1666 undef $handle;
1667 }); 1757 });
1668 1758
1669The reason to use C<on_error> is that TCP connections, due to latencies 1759The reason to use C<on_error> is that TCP connections, due to latencies
1670and packets loss, might get closed quite violently with an error, when in 1760and packets loss, might get closed quite violently with an error, when in
1671fact, all data has been received. 1761fact, all data has been received.
… …
1687 $handle->on_drain (sub { 1777 $handle->on_drain (sub {
1688 warn "all data submitted to the kernel\n"; 1778 warn "all data submitted to the kernel\n";
1689 undef $handle; 1779 undef $handle;
1690 }); 1780 });
1691 1781
1782If you just want to queue some data and then signal EOF to the other side,
1783consider using C<< ->push_shutdown >> instead.
1784
1785=item I want to contact a TLS/SSL server, I don't care about security.
1786
1787If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
1788simply connect to it and then create the AnyEvent::Handle with the C<tls>
1789parameter:
1790
1791 tcp_connect $host, $port, sub {
1792 my ($fh) = @_;
1793
1794 my $handle = new AnyEvent::Handle
1795 fh => $fh,
1796 tls => "connect",
1797 on_error => sub { ... };
1798
1799 $handle->push_write (...);
1800 };
1801
1802=item I want to contact a TLS/SSL server, I do care about security.
1803
1804Then you should additionally enable certificate verification, including
1805peername verification, if the protocol you use supports it (see
1806L<AnyEvent::TLS>, C<verify_peername>).
1807
1808E.g. for HTTPS:
1809
1810 tcp_connect $host, $port, sub {
1811 my ($fh) = @_;
1812
1813 my $handle = new AnyEvent::Handle
1814 fh => $fh,
1815 peername => $host,
1816 tls => "connect",
1817 tls_ctx => { verify => 1, verify_peername => "https" },
1818 ...
1819
1820Note that you must specify the hostname you connected to (or whatever
1821"peername" the protocol needs) as the C<peername> argument, otherwise no
1822peername verification will be done.
1823
1824The above will use the system-dependent default set of trusted CA
1825certificates. If you want to check against a specific CA, add the
1826C<ca_file> (or C<ca_cert>) arguments to C<tls_ctx>:
1827
1828 tls_ctx => {
1829 verify => 1,
1830 verify_peername => "https",
1831 ca_file => "my-ca-cert.pem",
1832 },
1833
1834=item I want to create a TLS/SSL server, how do I do that?
1835
1836Well, you first need to get a server certificate and key. You have
1837three options: a) ask a CA (buy one, use cacert.org etc.) b) create a
1838self-signed certificate (cheap. check the search engine of your choice,
1839there are many tutorials on the net) or c) make your own CA (tinyca2 is a
1840nice program for that purpose).
1841
1842Then create a file with your private key (in PEM format, see
1843L<AnyEvent::TLS>), followed by the certificate (also in PEM format). The
1844file should then look like this:
1845
1846 -----BEGIN RSA PRIVATE KEY-----
1847 ...header data
1848 ... lots of base64'y-stuff
1849 -----END RSA PRIVATE KEY-----
1850
1851 -----BEGIN CERTIFICATE-----
1852 ... lots of base64'y-stuff
1853 -----END CERTIFICATE-----
1854
1855The important bits are the "PRIVATE KEY" and "CERTIFICATE" parts. Then
1856specify this file as C<cert_file>:
1857
1858 tcp_server undef, $port, sub {
1859 my ($fh) = @_;
1860
1861 my $handle = new AnyEvent::Handle
1862 fh => $fh,
1863 tls => "accept",
1864 tls_ctx => { cert_file => "my-server-keycert.pem" },
1865 ...
1866
1867When you have intermediate CA certificates that your clients might not
1868know about, just append them to the C<cert_file>.
1869
1692=back 1870=back
1693 1871
1694 1872
1695=head1 SUBCLASSING AnyEvent::Handle 1873=head1 SUBCLASSING AnyEvent::Handle
1696 1874

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines