NEWS.md
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.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.