[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Handle.pm

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.240 by root, Tue Dec 17 16:43:15 2013 UTC vs.
Revision 1.249 by root, Sat Nov 26 03:34:50 2016 UTC

    $cv->recv;
 =head1 DESCRIPTION
-This is a helper module to make it easier to do event-based I/O on
+This is a helper module to make it easier to do event-based I/O
-stream-based filehandles (sockets, pipes, and other stream things).
+on stream-based filehandles (sockets, pipes, and other stream
+things). Specifically, it doesn't work as expected on files, packet-based
+sockets or similar things.
 The L<AnyEvent::Intro> tutorial contains some well-documented
 AnyEvent::Handle examples.
 In the following, where the documentation refers to "bytes", it means
 package AnyEvent::Handle;
 use Scalar::Util ();
 use List::Util ();
 use Carp ();
-use Errno qw(EAGAIN EINTR);
+use Errno qw(EAGAIN EWOULDBLOCK EINTR);
 use AnyEvent (); BEGIN { AnyEvent::common_sense }
 use AnyEvent::Util qw(WSAEWOULDBLOCK);
 our $VERSION = $AnyEvent::VERSION;
 =item fh => $filehandle     [C<fh> or C<connect> MANDATORY]
 The filehandle this L<AnyEvent::Handle> object will operate on.
 NOTE: The filehandle will be set to non-blocking mode (using
-C<AnyEvent::Util::fh_nonblocking>) by the constructor and needs to stay in
+C<AnyEvent::fh_unblock>) by the constructor and needs to stay in
 that mode.
 =item connect => [$host, $service]      [C<fh> or C<connect> MANDATORY]
 Try to connect to the specified host and service (port), using
 The peer's numeric host and port (the socket peername) are passed as
 parameters, together with a retry callback. At the time it is called the
 read and write queues, EOF status, TLS status and similar properties of
 the handle will have been reset.
-It is not allowed to use the read or write queues while the handle object
-is connecting.
 If, for some reason, the handle is not acceptable, calling C<$retry> will
 continue with the next connection target (in case of multi-homed hosts or
 SRV records there can be multiple connection endpoints). The C<$retry>
 callback can be invoked after the connect callback returns, i.e. one can
 =item json => L<JSON>, L<JSON::PP> or L<JSON::XS> object
 This is the json coder object used by the C<json> read and write types.
 If you don't supply it, then AnyEvent::Handle will create and use a
-suitable one (on demand), which will write and expect UTF-8 encoded JSON
+suitable one (on demand), which will write and expect UTF-8 encoded
+JSON texts (either using L<JSON::XS> or L<JSON>). The written texts are
+guaranteed not to contain any newline character.
+For security reasons, this encoder will likely I<not> handle numbers and
+strings, only arrays and objects/hashes. The reason is that originally
+JSON was self-delimited, but Dougles Crockford thought it was a splendid
+idea to redefine JSON incompatibly, so this is no longer true.
+For protocols that used back-to-back JSON texts, this might lead to
+run-ins, where two or more JSON texts will be interpreted as one JSON
-texts.
+text.
+For this reason, if the default encoder uses L<JSON::XS>, it will default
+to not allowing anything but arrays and objects/hashes, at least for the
+forseeable future (it will change at some point). This might or might not
+be true for the L<JSON> module, so this might cause a security issue.
+If you depend on either behaviour, you should create your own json object
+and pass it in explicitly.
 =item cbor => L<CBOR::XS> object
 This is the cbor coder object used by the C<cbor> read and write types.
 If you don't supply it, then AnyEvent::Handle will create and use a
 suitable one (on demand), which will write CBOR without using extensions,
-if possible. texts.
+if possible.
 Note that you are responsible to depend on the L<CBOR::XS> module if you
 want to use this functionality, as AnyEvent does not have a dependency on
 it itself.
    # with AnyEvent::Handle, do them a favour.
    my $type = getsockopt $self->{fh}, Socket::SOL_SOCKET (), Socket::SO_TYPE ();
    Carp::croak "AnyEvent::Handle: only stream sockets supported, anything else will NOT work!"
       if Socket::SOCK_STREAM () != (unpack "I", $type) && defined $type;
-   AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
+   AnyEvent::fh_unblock $self->{fh};
    $self->{_activity}  =
    $self->{_ractivity} =
    $self->{_wactivity} = AE::now;
    $_[0]{oobinline} = $_[1];
    eval {
       local $SIG{__DIE__};
       setsockopt $_[0]{fh}, Socket::SOL_SOCKET (), Socket::SO_OOBINLINE (), int $_[1]
-         if $_[0]{fh};
-   };
-}
-=item $handle->keepalive ($boolean)
-Enables or disables the C<keepalive> setting (see constructor argument of
-the same name for details).
-=cut
-sub keepalive {
-   $_[0]{keepalive} = $_[1];
-   eval {
-      local $SIG{__DIE__};
-      setsockopt $_[0]{fh}, Socket::SOL_SOCKET (), Socket::SO_KEEPALIVE (), int $_[1]
          if $_[0]{fh};
    };
 }
 =item $handle->on_starttls ($cb)
             $self->{on_drain}($self)
                if $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf})
                   && $self->{on_drain};
             delete $self->{_ww} unless length $self->{wbuf};
-         } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
+         } elsif ($! != EAGAIN && $! != EINTR && $! != EWOULDBLOCK && $! != WSAEWOULDBLOCK) {
             $self->_error ($!, 1);
          }
       };
       # try to write data immediately
 Encodes the given hash or array reference into a JSON object. Unless you
 provide your own JSON object, this means it will be encoded to JSON text
 in UTF-8.
+The default encoder might or might not handle every type of JSON value -
+it might be limited to arrays and objects for security reasons. See the
+C<json> constructor attribute for more details.
-JSON objects (and arrays) are self-delimiting, so you can write JSON at
+JSON objects (and arrays) are self-delimiting, so if you only use arrays
-one end of a handle and read them at the other end without using any
+and hashes, you can write JSON at one end of a handle and read them at the
-additional framing.
+other end without using any additional framing.
-The generated JSON text is guaranteed not to contain any newlines: While
+The JSON text generated by the default encoder is guaranteed not to
-this module doesn't need delimiters after or between JSON texts to be
+contain any newlines: While this module doesn't need delimiters after or
-able to read them, many other languages depend on that.
+between JSON texts to be able to read them, many other languages depend on
+them.
 A simple RPC protocol that interoperates easily with other languages is
 to send JSON arrays (or objects, although arrays are usually the better
 choice as they mimic how function argument passing works) and a newline
 after each JSON text:
 };
 =item regex => $accept[, $reject[, $skip], $cb->($handle, $data)
 Makes a regex match against the regex object C<$accept> and returns
-everything up to and including the match.
+everything up to and including the match. All the usual regex variables
+($1, %+ etc.) from the regex match are available in the callback.
 Example: read a single line terminated by '\n'.
    $handle->push_read (regex => qr<\n>, sub { ... });
 accomodate protocol changes.
 This read type does not rely on L<AnyEvent::TLS> (and thus, not on
 L<Net::SSLeay>).
-=item tls_autostart => $tls[, $tls_ctx]
+=item tls_autostart => [$tls_ctx, ]$tls
 Tries to detect a valid SSL or TLS handshake. If one is detected, it tries
 to start tls by calling C<starttls> with the given arguments.
 In practise, C<$tls> must be C<accept>, or a Net::SSLeay context that has
 See C<tls_detect> above for more details.
 Example: give the client a chance to start TLS before accepting a text
 line.
-   $hdl->push_read (tls_detect => "accept");
+   $hdl->push_read (tls_autostart => "accept");
    $hdl->push_read (line => sub {
       print "received ", ($_[0]{tls} ? "encrypted" : "cleartext"), " <$_[1]>\n";
    });
 =cut
          } elsif (defined $len) {
             delete $self->{_rw};
             $self->{_eof} = 1;
             $self->_drain_rbuf;
-         } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
+         } elsif ($! != EAGAIN && $! != EINTR && $! != EWOULDBLOCK && $! != WSAEWOULDBLOCK) {
             return $self->_error ($!, 1);
          }
       };
    }
 }
    $self->{tls}     = $tls = $self->{tls_ctx}->_get_session ($tls, $self, $self->{peername});
    # basically, this is deep magic (because SSL_read should have the same issues)
    # but the openssl maintainers basically said: "trust us, it just works".
    # (unfortunately, we have to hardcode constants because the abysmally misdesigned
-   # and mismaintained ssleay-module doesn't even offer them).
+   # and mismaintained ssleay-module didn't offer them for a decade or so).
    # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html
    #
    # in short: this is a mess.
    #
    # note that we do not try to keep the length constant between writes as we are required to do.
    # we assume that most (but not all) of this insanity only applies to non-blocking cases,
    # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
    # have identity issues in that area.
-#   Net::SSLeay::CTX_set_mode ($ssl,
+#   Net::SSLeay::set_mode ($ssl,
 #      (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
 #      | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
-   Net::SSLeay::CTX_set_mode ($tls, 1|2);
+   Net::SSLeay::set_mode ($tls, 1|2);
    $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
    $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
    Net::SSLeay::BIO_write ($self->{_rbio}, $self->{rbuf});
       push @linger, AE::io $fh, 1, sub {
          my $len = syswrite $fh, $wbuf, length $wbuf;
          if ($len > 0) {
             substr $wbuf, 0, $len, "";
-         } elsif (defined $len || ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK)) {
+         } elsif (defined $len || ($! != EAGAIN && $! != EINTR && $! != EWOULDBLOCK && $! != WSAEWOULDBLOCK)) {
             @linger = (); # end
          }
       };
       push @linger, AE::timer $linger, 0, sub {
          @linger = ();

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.240 by root, Tue Dec 17 16:43:15 2013 UTC vs. Revision 1.249 by root, Sat Nov 26 03:34:50 2016 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.240 by root, Tue Dec 17 16:43:15 2013 UTC vs.
Revision 1.249 by root, Sat Nov 26 03:34:50 2016 UTC