mirai.promises::as.promise() and
promises::is.promising() to enable ‘recvAio’ promises.serial_config() now validates all arguments and returns
them as a list. Full validation is also performed when the option is set
for additional safety.reply() to always return even when there is an
evaluation error. This allows it to be used safely in a loop without
exiting early, for example.next_config().serial_config() to create configurations that can
be set on Sockets to make use of custom serialization and
unserialization functions for reference objects (plugs into the
‘refhook’ system of native R serialization).'opt<-'() now accepts the special option ‘serial’
for Sockets, which takes a configuration returned from
serial_config().is_ncurl_session() as a validation function.collect_pipe() for obtaining the underlying Pipe
from a ‘recvAio’. This affords more granular control of connections,
with the ability to close individual pipes.send_aio() now accept a Pipe to direct messages to a
specific peer for supported protocols such as ‘poly’.next_config() is now deprecated and
defunct, in favour of the new serial_config().ncurl_session() now returns ‘errorValue’ 7 (Object
closed) when attempting to transact over a closed session or closing a
closed session, rather than throwing an error.collect_aio() and collect_aio_() no longer
append empty names when acting on lists of Aios where there were none in
the first place.stats and utils
base packages.promises::as.promise() and
promises::is.promising() to enable ‘ncurlAio’
promises.x[] as a new method for an Aio x
equivalent to collect_aio_(x), which waits for and collects
the data.request() specifying argument ‘cv’ other than NULL or a
‘conditionVariable’ will cause the pipe connection to be dropped when
the reply is (asynchronously) completed.strcat(),
recv_aio_signal() and request_signal().base64enc() and base64dec() in
favour of those from the {secretbase} package.msleep() now ignores negative values rather than taking
the absolute value.later is now relaxed to a soft ‘suggests’ dependency
(only required if using promises).promises is added as a soft ‘enhances’ dependency.collect_aio() and collect_aio_() to
wait for and collect the data of an Aio or list of Aios.unresolved(), call_aio(),
call_aio()_ and stop_aio() now all accept a
list of Aios.pipe_notify() gains the ability to specify ‘cv’ as NULL
to cancel previously-set signals.ncurl_aio() modified internally to support conversion
of ‘ncurlAio’ to event-driven promises.recv_aio() and request() add argument ‘cv’
allowing optional signalling of a condition variable. The separate
functions recv_aio_signal() and
request_signal() are deprecated.strcat() is deprecated as considered non-core - it is
recommended to replace usage with sprintf().status_code() now returns the status code combined with
the explanation as a character string.unresolved(),
call_aio() and call_aio_().later package to provide the
foundation for truly event-driven (non-polling) promises (thanks @jcheng5 for the initial
prototype in #28), where side-effects are enacted asynchronously upon
aio completion.
request() and request_signal() modified
internally to support conversion of ‘recvAio’ to event-driven
promises.later dependency ensures asynchronous R code is always
run on the main R thread.later is lazily loaded the first time a promise is
used, and hence does not impact the load time of nanonext
or dependent packages.stop_aio() now causes the ‘aio’ to resolve to an
‘errorValue’ of 20 (Operation canceled) if successfully stopped.nng_error() now returns the error code combined with
the message as a character string.next_config() gains argument ‘class’ and ‘vec’,
enabling custom serialization for all reference object types supported
by R serialization.socket().Please note the following potentially breaking changes, and only update when ready:
send() and recv()
aligned to non-blocking for both Sockets and Contexts (facilitated by
synchronous context sends in NNG since v1.6.0).ncurl(), ncurl_aio() and
ncurl_session() now restrict ‘header’ and ‘response’
arguments to character vectors only, no longer accepting lists (for
safety and performance).sha1() is removed as a hash option.Other changes:
messenger() specifying ‘auth’ now works reliably on
endpoints using different R versions/platforms due to the above hashing
portability fix.This is a major performance and stability release bundling the ‘libnng’ v1.7.0 source code.
pipe_notify() argument ‘flag’ allows supplying a signal
to be raised on a flag being set upon a pipe event.random() now explicitly limits argument ‘n’ to values
between 0 and 1024.next_config() now returns a pairlist (of the registered
serialization functions) rather than a list (for efficiency)..until() is removed.This is a major stability release bundling the ‘libnng’ v1.6.0 source code.
call_aio_(), a user-interruptible version of
call_aio() suitable for interactive use.wait_() and until_()
user-interruptible versions of wait() and
until() suitable for interactive use.%~>% signal forwarder from one
‘conditionVariable’ to another.next_config() replaces nextmode() with the
following improvements:
until() updated to be identical to
.until(), returning FALSE instead of TRUE if the timeout
has been reached.reap() updated to no longer warn in cases it returns an
‘errorValue’.pipe_notify() arguments ‘add’, ‘remove’ and ‘flag’ now
default to FALSE instead of TRUE for easier selective specification of
the events to signal.ncurl() with ‘follow’ set to TRUE when the server
returns a missing or invalid relocation address.nextmode() configures settings for send mode ‘next’.
Registers hook functions for custom serialization and unserialization of
reference objects (such as those accessed via an external pointer)..until() contains revised behaviour for this
synchronisation primitive, returning FALSE instead of TRUE if the
timeout has been reached. This function will replace
until() in a future package version.lock() supplying ‘cv’ has improved behaviour which
locks the socket whilst allowing for both initial connections and
re-connections (when the ‘cv’ is registered for both add and remove pipe
events).request() argument ‘ack’ removed due to stability
considerations.request() adds logical argument ‘ack’, which sends an
ack(nowledgement) back to the rep node upon a successful async message
receive.reap() implemented as a faster alternative to
close() for Sockets, Contexts, Listeners and Dialers -
avoiding S3 method dispatch, hence works for unclassed external pointers
created by .context().random() updated to use the Mbed TLS library to
generate random bytes. Adds a ‘convert’ argument for specifying whether
to return a raw vector or character string.write_cert() has been optimised for higher efficiency
and faster operation.send() and recv() over contexts now use
more efficient synchronous methods where available.ncurl_aio() has been separated into a dedicated
function for async http requests.mode = 'string' as a faster
alternative to ‘character’ when receiving a scalar value.Please review the following potentially breaking changes, and only update when ready:
ncurl() argument ‘async’ is retired. Please use
ncurl_aio() for asynchronous requests.ncurl() now always returns the response message body at
$data whether convert is TRUE or FALSE.cv_reset() and cv_signal() now both return
invisible zero rather than NULL.device() is removed partially due to its
non-interruptible blocking behaviour.Other changes:
ncurl():
This version contains performance enhancements which have resulted in potentially breaking changes; please review carefully and only update when ready.
base64dec() argument ‘convert’ now accepts NA as an
input, which unserializes back to the original object.ncurl() etc. gain higher performance raw to character
conversion, resulting in the following changes:
$raw.timed_signal()
removed.tls+tcp:// and
wss:// for scalability protocols.
listen() and dial() gain the argument
‘tls’ for supplying a TLS configuration objectwrite_cert() generates 4096 bit RSA keys and
self-signed X.509 certificates for use with
tls_config().weakref(), weakref_key() and
weakref_value() implement an interface to R’s weak
reference system. These may be used for synchronising the lifetimes of
objects with reference objects such as Sockets or Aios, or creating
read-only objects accessible by the weakref value alone.strcat() provides a simple, fast utility to concatenate
two strings.tls_config() now accepts a relative path if filenames
are supplied for the ‘client’ or ‘server’ arguments.base64enc() failed for objects
exceeding a certain size.stream() has been updated internally for additional
robustness.The package is now compatible (again) with currently released ‘libnng’ versions. It will attempt to use system ‘libnng’ versions >= 1.5 where detected, and only compile the bundled library where necessary.
tls_config() to create re-usable TLS
configurations from certificate / key files (or provided directly as
text).ncurl(), ncurl_session()
and stream() retired in favour of ‘tls’ which takes a TLS
Configuration object created by tls_config() rather than a
PEM certificate directly.nanonext_version() in favour of the existing
nng_version(), along with
utils::packageVersion() if required, for greater
flexibility.... argument for context() -
retained for compatibility with the ‘verify’ argument, which was removed
in the previous release.cv_signal() and timed_signal()
for signalling a condition variable, the latter after a specified time
(from a newly-created thread)..context(), a performance alternative to
context() that does not create the full object.nanonext_version() for providing the
package version, NNG and mbed TLS library versions in a single
string.ncurl() gains a ‘timeout’ argument.context() (changed to ‘…’
for compatibility) as request() and
request_signal() have been rendered safe internally for use
with timeouts.msleep() has been
changed to ‘time’ from ‘msec’.pipe_notify(), lock() and
unlock() now error if unsuccessful rather than returning
with a warning.lock() and unlock() implemented to prevent
further pipe connections from being established at a socket, optionally
tied to the value of a condition variable.context() gains the argument ‘verify’ with a default of
TRUE. This adds additional protection to notably the
request() and request_signal() functions when
using timeouts, as these require a connection to be present.until() now works as intended.msg_pipe() and
'weakref<-'() to maintain simplicity of user
interface.cv(), wait(),
until(), cv_value(), and
cv_reset().recv_aio_signal() and
request_signal().pipe_notify() signals up to 2 condition variables
whenever pipes are added or removed at a socket.msg_pipe() to return the pipe connection
associated with a ‘recvAio’ message.sha1() cryptographic hash and HMAC
generation function from the ‘Mbed TLS’ library (for secure
applications, use one of the SHA-2 algorithms instead).'weakref<-'() exposes
R_MakeWeakRef from R’s C API. Useful for keeping objects
alive for as long as required by a dependent object.ncurl_session() gains a ‘timeout’ argument, and returns
an ‘errorValue’ with warning upon error.listen() and dial() gain the new logical
argument ‘error’ to govern the function behaviour upon error.stat(), an interface to the NNG statistics
framework. Can be used to return the number of currently connected pipes
for a socket, connection attempts for a listener/dialer etc.parse_url(), which parses a URL as per NNG.
Provides a fast and standardised method for obtaining parts of a URL
string.Please review the following potentially breaking changes, and only update when ready:
socket() specifying either ‘dial’ or ‘listen’, a
failure to either dial or listen (due to an invalid URL for example)
will now error rather than return a socket with a warning. This is safer
behaviour that should make it easier to detect bugs in user code.opt() and 'opt<-'() have been
implemented as more ergonomic options getter and setter functions to
replace getopt() and setopt(). These will
error if the option does not exist / input value is invalid etc.subscribe(), unsubscribe() and
survey_time() now return the Socket or Context invisibly
rather than an exit code, and will error upon invalid input etc.survey_time() argument name is now ‘value’, with a
default of 1000L.$opt, $listener_opt,
and $dialer_opt re-implemented to either get or set values
depending on whether the ‘value’ parameter has been supplied.Other changes:
ncurl_session() and transact()
providing high-performance, re-usable http(s) connections.dial(),
socket() and nano() now accepts NA for
starting the dialer synchronously - this is less resilient if a
connection is not immediately possible, but avoids subtle errors from
attempting to use the socket before an asynchronous dial has
completed.messenger() is faster to connect and exits gracefully
in case of a connection error.nano_init().getopt(), the counterpart to
setopt() for retrieving the value of options on
objects.setopt() interface is simplified, with the type now
inferred from the value supplied.ncurl() now returns redirect addresses as the response
header ‘Location’. This is so that HTTP data can also be returned at
$data where this is provided.status_code() utility returns a translation of HTTP
response status codes.Please review the following potentially breaking changes, and only update when ready:
socket(), context() and
stream() will now error rather than return an ‘errorValue’.
The error value is included in the error message.send_aio() and recv_aio() now always
return an integer ‘errorValue’ at $result and
$data respectively.recv() and recv_aio() now return an
integer ‘errorValue’ at each of $raw and $data
when ‘keep.raw’ is set to TRUE.ncurl() now returns an integer ‘errorValue’ at each of
$status, $headers, $raw and
$data for both sync and async. Where redirects are not
followed, the address is now returned as a character string at
$data.send(), send_aio(), recv(),
recv_aio() and ncurl(), ‘errorValues’ are now
returned silently without an accompanying warning. Use
is_error_value() to explicitly check for errors.nano_init() is deprecated due to the above change in
behaviour.send() no longer has a ‘…’ argument. This has had no
effect since 0.6.0, but will now error if additional arguments are
provided (please check and remove previous uses of the argument ‘echo’).
Also no longer returns invisibly for consistency with
recv().listen() and dial() now only take a socket
as argument; for nano objects, the $listen() and
$dial() methods must be used instead.nano() now creates a nano object with method
$context_open() for applicable protocols. Opening a context
will attach a context at $context and a
$context_close() method. When a context is active, all
object methods apply to the context instead of the socket. Method
$socket_setopt() renamed to $setopt() as it
can be used on the socket or active context as applicable.Other changes:
send()/recv() arguments for ‘mode’
implemented in 0.5.3 are now documented and considered part of the API.
This is a performance feature that skips matching the character argument
value.base64dec() encounters
invalid input data. Error messages have been revised to be more
accurate.$ method for ‘recvAio’ objects for when the
object has been stopped using stop_aio().$listen() or $dial() methods of
a nano object specifying ‘autostart = FALSE’ now attaches the
$listener_start() or $dialer_start() method
for the most recently added listener/dialer.device() no longer prompts for confirmation in
interactive environments - as device creation is only successful when
binding 2 raw mode sockets, there is little scope for accidental
use.base64enc() and base64dec()
base64 encoding and decoding using the ‘Mbed TLS’ library.sha224(), sha256(), sha384()
and sha512() functions gain an argument ‘convert’ to
control whether to return a raw vector or character string.ncurl() gains the argument ‘follow’ (default FALSE) to
control whether redirects are automatically followed.Please review the following potentially breaking changes, and only update when ready:
send() now returns an integer exit code in all cases.
The ‘echo’ argument has been replaced by ‘…’, and specifying ‘echo’ no
longer has any effect.recv(), recv_aio() and
request() now default to ‘keep.raw’ = FALSE to return only
the sent object.ncurl() argument ‘request’ renamed to ‘response’ for
specifying response headers to return (to avoid confusion); new argument
‘follow’ (placed between ‘convert’ and ‘method’) controls whether
redirects are followed, and there is no longer a user prompt in
interactive environments.sha224(), sha256(), sha384()
and sha512() functions no longer return ‘nanoHash’ objects,
but a raw vector or character string depending on the new argument
‘convert’.Other changes:
socket() and nano() now accept non-missing
NULL ‘listen’ and ‘dial’ arguments, allowing easier programmatic
use.send(), recv(),
send_aio(), recv_aio(), setopt(),
subscribe(), unsubscribe() and
survey_time() are no longer S3 generics for enhanced
performance.messenger() uses longer SHA-512 hash for
authentication; fixes errors creating a connnection not being
shown.new.env() interface was implemented.sha224(), sha256(),
sha384() and sha512() series of fast,
optimised cryptographic hash and HMAC generation functions using the
‘Mbed TLS’ library.ncurl() and stream() gain the argmument
‘pem’ for optionally specifying a certificate authority certificate
chain PEM file for authenticating secure sites.ncurl() gains the argument ‘request’ for specifying
response headers to return.ncurl() now returns additional $status
(response status code) and $headers (response headers)
fields.messenger() gains the argument ‘auth’ for
authenticating communications based on a pre-shared key.random() gains the argument ‘n’ for generating a vector
of random numbers.nng_version() now returns the ‘Mbed TLS’ library
version number.device() gains a confirmation prompt when running
interactively for more safety.ncurl() that caused a 26 cryptography
error with certain secure sites using SNI.msleep() made safe (does not block) in case of
non-numeric input.mclock(), msleep() and
random() utilities exposing the library functions for
timing and cryptographic RNG respectively.socket() gains the ability to open ‘raw’ mode sockets.
Please note: this is not for general use - do not set this argument
unless you have a specific need, such as for use with
device() (refer to NNG documentation).device() which creates a socket forwarder or
proxy. Warning: use this in a separate process as this function blocks
with no ability to interrupt./usr/local. Note that this is a
manual setting allowing for custom NNG builds, and requires a version of
NNG at least as recent as 722bf46.unresolvedValue returned by
Aios (thanks @lionel-
#3).$context() method added for creating new contexts from
nano Objects using supported protocols (i.e. req, rep, sub, surveyor,
respondent) - this replaces the context() function for nano
Objects.subscribe() and unsubscribe() now accept a
topic of any atomic type (not just character), allowing pub/sub to be
used with integer, double, logical, complex, or raw vectors.is_nano() and
is_aio().subscribe(),
unsubscribe(), and survey_time() gain
nanoContext methods.$raw and $data
if keep.raw = TRUE.send_ctx(), recv_ctx() and
logging removed.stream() interface exposes low-level byte stream
functionality in the NNG library, intended for communicating with
non-NNG endpoints, including but not limited to websocket servers.ncurl() adds an ‘async’ option to perform HTTP requests
asynchronously, returning immediately with a ‘recvAio’. Adds explicit
arguments for HTTP method, headers (which takes a named list or
character vector) and request data, as well as to specify if conversion
from raw bytes is required.messenger() function implements a multi-threaded
console-based messaging system using NNG’s scalability protocols
(currently as proof of concept).nano_init() function intended to be called
immediately after package load to set global options.warnings() and flexibility in handling via setting
options().send() and recv() functions, and
their asynchronous counterparts send_aio() and
recv_aio(), are now S3 generics and can be used across
Sockets, Contexts and Streams.send() and
recv() now allows an integer value for setting a
timeout.send_ctx() and recv_ctx() are deprecated
and will be removed in a future package version - the methods for
send() and recv() should be used instead.logging() is now defunct.$result, $data and
$raw now resolve automatically without requiring
call_aio(). Access directly and an ‘unresolved’ logical NA
value will be returned if the Aio operation is yet to complete.unresolved() added as an auxiliary function to query
whether an Aio is unresolved, for use in control flow statements.is_error_value() helper function
included.is_nul_byte() added as a helper function for
request/reply setups.survey_time() added as a convenience function for
surveyor/respondent patterns.logging() function to specify a global package logging
level - ‘error’ or ‘info’. Automatically checks the environment variable
‘NANONEXT_LOG’ on package load and then each time
logging(level = "check") is called.ncurl() adds a ‘…’ argument. Support for HTTP methods
other than GET.listen() and dial() now return (invisible)
zero rather than NULL upon success for consistency with other
functions.opts to avoid
clash with base R ‘options’.nng_timer() utility as a
non-essential function.send_aio() and recv_aio() now return Aio
objects, for which the results may be called using
call_aio().request() and reply() functions
implement the full logic of an RPC client/server, allowing processes to
run concurrently on the client and server.
ncurl() minimalistic http(s) client.nng_timer() utility as a demonstration of NNG’s
multithreading capabilities.send()/recv(), gain a revised ‘mode’
argument.
send_ctx() and recv_ctx() for
consistency.$socket_close() method of nano objects has been
renamed $close() to better align with the functional
API.