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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.237 by root, Tue Jul 30 23:14:32 2013 UTC vs.
Revision 1.241 by root, Fri Sep 5 22:17:26 2014 UTC

 callback.
 This callback will only be called on TLS shutdowns, not when the
 underlying handle signals EOF.
-=item json => JSON or JSON::XS object
+=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.
-Note that you are responsible to depend on the JSON module if you want to
+Note that you are responsible to depend on the L<CBOR::XS> module if you
-use this functionality, as AnyEvent does not have a dependency itself.
+want to use this functionality, as AnyEvent does not have a dependency on
+it itself.
 =back
 =cut
 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 others is to send
+A simple RPC protocol that interoperates easily with other languages is
-JSON arrays (or objects, although arrays are usually the better choice as
+to send JSON arrays (or objects, although arrays are usually the better
-they mimic how function argument passing works) and a newline after each
+choice as they mimic how function argument passing works) and a newline
-JSON text:
+after each JSON text:
    $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever
    $handle->push_write ("\012");
 An AnyEvent::Handle receiver would simply use the C<json> read type and
    $handle->push_read (json => sub { my $array = $_[1]; ... });
 Other languages could read single lines terminated by a newline and pass
 this line into their JSON decoder of choice.
+=item cbor => $perl_scalar
+Encodes the given scalar into a CBOR value. Unless you provide your own
+L<CBOR::XS> object, this means it will be encoded to a CBOR string not
+using any extensions, if possible.
+CBOR values are self-delimiting, so you can write CBOR at one end of
+a handle and read them at the other end without using any additional
+framing.
+A simple nd very very fast RPC protocol that interoperates with
+other languages is to send CBOR and receive CBOR values (arrays are
+recommended):
+   $handle->push_write (cbor => ["method", "arg1", "arg2"]); # whatever
+An AnyEvent::Handle receiver would simply use the C<cbor> read type:
+   $handle->push_read (cbor => sub { my $array = $_[1]; ... });
 =cut
 sub json_coder() {
    eval { require JSON::XS; JSON::XS->new->utf8 }
-      || do { require JSON; JSON->new->utf8 }
+      || do { require JSON::PP; JSON::PP->new->utf8 }
 }
 register_write_type json => sub {
    my ($self, $ref) = @_;
-   my $json = $self->{json} ||= json_coder;
+   ($self->{json} ||= json_coder)
-   $json->encode ($ref)
+      ->encode ($ref)
+};
+sub cbor_coder() {
+   require CBOR::XS;
+   CBOR::XS->new
+}
+register_write_type cbor => sub {
+   my ($self, $scalar) = @_;
+   ($self->{cbor} ||= cbor_coder)
+      ->encode ($scalar)
 };
 =item storable => $reference
 Freezes the given reference using L<Storable> and writes it to the
 =item json => $cb->($handle, $hash_or_arrayref)
 Reads a JSON object or array, decodes it and passes it to the
 callback. When a parse error occurs, an C<EBADMSG> error will be raised.
-If a C<json> object was passed to the constructor, then that will be used
+If a C<json> object was passed to the constructor, then that will be
-for the final decode, otherwise it will create a JSON coder expecting UTF-8.
+used for the final decode, otherwise it will create a L<JSON::XS> or
+L<JSON::PP> coder object expecting UTF-8.
 This read type uses the incremental parser available with JSON version
-2.09 (and JSON::XS version 2.2) and above. You have to provide a
+2.09 (and JSON::XS version 2.2) and above.
-dependency on your own: this module will load the JSON module, but
-AnyEvent does not depend on it itself.
 Since JSON texts are fully self-delimiting, the C<json> read and write
 types are an ideal simple RPC protocol: just exchange JSON datagrams. See
 the C<json> write type description, above, for an actual example.
    my ($self, $cb) = @_;
    my $json = $self->{json} ||= json_coder;
    my $data;
-   my $rbuf = \$self->{rbuf};
    sub {
       my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
       if ($ref) {
          ()
       } else {
          $_[0]{rbuf} = "";
+         ()
+      }
+   }
+};
+=item cbor => $cb->($handle, $scalar)
+Reads a CBOR value, decodes it and passes it to the callback. When a parse
+error occurs, an C<EBADMSG> error will be raised.
+If a L<CBOR::XS> object was passed to the constructor, then that will be
+used for the final decode, otherwise it will create a CBOR coder without
+enabling any options.
+You have to provide a dependency to L<CBOR::XS> on your own: this module
+will load the L<CBOR::XS> module, but AnyEvent does not depend on it
+itself.
+Since CBOR values are fully self-delimiting, the C<cbor> read and write
+types are an ideal simple RPC protocol: just exchange CBOR datagrams. See
+the C<cbor> write type description, above, for an actual example.
+=cut
+register_read_type cbor => sub {
+   my ($self, $cb) = @_;
+   my $cbor = $self->{cbor} ||= cbor_coder;
+   my $data;
+   sub {
+      my (@value) = eval { $cbor->incr_parse ($_[0]{rbuf}) };
+      if (@value) {
+         $cb->($_[0], @value);
+         1
+      } elsif ($@) {
+         # error case
+         $cbor->incr_reset;
+         $_[0]->_error (Errno::EBADMSG);
+         ()
+      } else {
          ()
       }
    }
 };
 sub _dotls {
    my ($self) = @_;
    my $tmp;
-   if (length $self->{_tls_wbuf}) {
+   while (length $self->{_tls_wbuf}) {
-      while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
+      if (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) <= 0) {
-         substr $self->{_tls_wbuf}, 0, $tmp, "";
+         $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
+         return $self->_tls_error ($tmp)
+            if $tmp != $ERROR_WANT_READ
+               && ($tmp != $ERROR_SYSCALL || $!);
+         last;
       }
-      $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
+      substr $self->{_tls_wbuf}, 0, $tmp, "";
-      return $self->_tls_error ($tmp)
-         if $tmp != $ERROR_WANT_READ
-            && ($tmp != $ERROR_SYSCALL || $!);
    }
    while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
       unless (length $tmp) {
          $self->{_on_starttls}
       $self->{_tls_rbuf} .= $tmp;
       $self->_drain_rbuf;
       $self->{tls} or return; # tls session might have gone away in callback
    }
-   $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
+   $tmp = Net::SSLeay::get_error ($self->{tls}, -1); # -1 is not neccessarily correct, but Net::SSLeay doesn't tell us
    return $self->_tls_error ($tmp)
       if $tmp != $ERROR_WANT_READ
          && ($tmp != $ERROR_SYSCALL || $!);
    while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.237 by root, Tue Jul 30 23:14:32 2013 UTC vs. Revision 1.241 by root, Fri Sep 5 22:17:26 2014 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.237 by root, Tue Jul 30 23:14:32 2013 UTC vs.
Revision 1.241 by root, Fri Sep 5 22:17:26 2014 UTC