[gnunet-scheme] branch master updated (eda9192 -> a68c0d1)

[gnunet]

This is an automated email from the git hooks/post-receive script.

maxime-devos pushed a change to branch master
in repository gnunet-scheme.

    from eda9192  Remove now unused patches.
     new 4637a88  mq/prio-prefs: New macro 'prio-prefs'.
     new 1f6ddc4  doc: Document ‘send-message!’ and ‘priority-preferences’.
     new 91459b0  mq/prio-prefs: Rename pref:goodput to pref:good-throughput.
     new 4c59777  doc: Begin drafting the CADET API.
     new a68c0d1  doc/cadet: Draft documentation on CADET network messages.

The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 NEWS                          |   1 +
 doc/cadet.tm                  | 172 ++++++++++++++++++++++++++++++++++++++++++
 doc/scheme-gnunet.tm          |   6 +-
 doc/service-communication.tm  |  52 +++++++++++++
 gnu/gnunet/mq/prio-prefs.scm  |  13 +++-
 gnu/gnunet/mq/prio-prefs2.scm |   3 +-
 6 files changed, 242 insertions(+), 5 deletions(-)
 create mode 100644 doc/cadet.tm

diff --git a/NEWS b/NEWS
index ced0881..2425898 100644
--- a/NEWS
+++ b/NEWS
@@ -13,6 +13,7 @@
      a little more self-documenting and understandable.
    - Likewise, a new ‘c-type’ property has been defined, making
      cross-referencing between Scheme and C sources simpler.
+   - ‘send-message!’ and ‘priority-preferences’ are documented.
 * Changes since 0.1
 ** Features
    - A DHT client! (gnu gnunet dht client), documented in the manual
diff --git a/doc/cadet.tm b/doc/cadet.tm
new file mode 100644
index 0000000..0f2b68f
--- /dev/null
+++ b/doc/cadet.tm
@@ -0,0 +1,172 @@
+<TeXmacs|2.1>
+
+<project|scheme-gnunet.tm>
+
+<style|tmmanual>
+
+<\body>
+  Two arbitrary peers on GNUnet can communicate with the CADET<index|CADET>
+  service<\footnote>
+    With some restrictions: there must be a path between the nodes, in a
+    lossy and malicious network with few connections the connection will be
+    lossy, etc.
+  </footnote>. Before describing the API the software can use, some
+  background on CADET's capabilities is given.
+
+  <\warning>
+    To be implemented, this is a draft of the API!
+  </warning>
+
+  <section|Qualities and limitations \V avoiding reinventing the wheel>
+
+  <dfn|Channels><index|tunnel><\footnote>
+    They could have been called <em|connections>, but that means something
+    different in CADET.
+  </footnote> \U i.e., bidirectional communication channels between two peers
+  over CADET, are encrypted and authentication and hence are impractical to
+  eavesdrop on or be modified by an attacker<\footnote>
+    Assuming that the cryptography is not broken.
+  </footnote>. To aid reliability and performance, CADET aims to keep three
+  independent connections between the two peers so manually creating multiple
+  channels ought to be unnecessary.
+
+  The unit of information sent over a channel is a
+  <with|font-shape|italic|message> \U essentially, a bytevector. The software
+  can select multiple options: it can choose between <em|reliable> or
+  <em|unreliable>, <em|in-order> and <em|out-of-order> and <em|low-latency>
+  or <em|corked>, see <reference|mq-prio-prefs>.
+
+  <todo|ACKs for messages, opening, closing, window size>
+
+  <section|Addresses>
+
+  To contact a peer over CADET, the remote peer must have an <dfn|open
+  port><index|port> and the local peer needs to contact this port. The remote
+  peer\Uport identifier pair is called a <dfn|CADET address><index|CADET
+  address> in Scheme-GNUnet. A <dfn|CADET address> can be made with the
+  <scm|make-cadet-address> procedure:
+
+  <\explain>
+    <scm|(make-cadet-address <var|peer> <var|port>)>
+  <|explain>
+    Make a CADET address for the peer <var|peer> (a readable bytevector slice
+    containing a <scm|/peer-identity>) at the port <var|port> (a readable
+    bytevector slice containing a <scm|/hashcode:512>). The slices <var|peer>
+    and <var|port> are copied, so future changes to them do not have any
+    impact on the CADET address.
+
+    The predicate for CADET addresses is <scm|cadet-address?>. The peer and
+    port can be extracted with the accessors <scm|cadet-address-peer> and
+    <scm|cadet-address-port>.
+  </explain>
+
+  Guile has a generic interface for network addresses, see (guile)Network
+  Socket Address. If BSD socket integration is activated (see <todo|todo>),
+  this interface is extended to support CADET addresses. In particular,
+  <scm|sockaddr:fam> will return <scm|AF_CADET> (a symbol, also available as
+  the variable <scm|AF_CADET>) an <scm|sockaddr:addr> and <scm|sockaddr:port>
+  will return the peer and port respectively as a bytevector that should not
+  be modified<\footnote>
+    A copy is made to avoid letting buggy code mutate the CADET address, but
+    this is an implementation detail.
+  </footnote>.
+
+  <section|Listening at an address>
+
+  To listen at some address such that other peers can connect, the
+  <scm|open-port!> procedure is used.
+
+  <\explain>
+    (open-port! <var|server> <var|port> <var|connected> HANDLERS)
+  </explain|>
+
+  <section|Connecting to an address>
+
+  <section|Performing I/O \U GNUnet style>
+
+  <section|Performing I/O \U BSD style>
+
+  <scm|send>, <scm|recv!> (MSG_PEEK), getsockname \U\<gtr\> ???, getpeername
+  \U\<gtr\> ???, accept, listen, bind, shutdown
+
+  No reuseport
+
+  <section|BSD socket integration>
+
+  (AF_CADET, SOCK_RAW, 0) \U\<gtr\> GNUnet messages (with reliability
+  according to socket options).
+
+  (AF_CADET, SOCK_STREAM, 0) \U\<gtr\> TCP/CADET (VPN)
+
+  (AF_CADET, SOCK_DGRAM, 0) \U\<gtr\> UDP/CADET (VPN)
+
+  (AF_CADET, SOCK_SEQPACKET, 0) \U\<gtr\> UDP/CADET (VPN), in-order, reliable
+
+  (AF_CADET, SOCK_RDM, 0) \U\<gtr\> UDP/CADET (VPN), out-of-order, reliable
+
+  These sockets not dupable, don't have a fd.<todo|>
+
+  <section|Constructing and analysing network messages>
+
+  <todo|difference between channels and ports>
+
+  <todo|acknowledgement>
+
+  <todo|readable bytevector slices>
+
+  <todo|verify against GNUnet documentation>
+
+  <todo|analysis>
+
+  <\explain>
+    (construct-open-local-port <var|port>)<index|construct-open-local-port>
+  </explain|Create a new 
<scm|/:msg:cadet:local:port:open><index|/:msg:cadet:local:port:open>
+  message for instructing the service to open the port <var|port> at the
+  local peer.>
+
+  <\explain>
+    (construct-close-local-port <var|port>)<index|construct-close-local-port>
+  </explain|Crreate a new 
<scm|/:msg:cadet:local:port:close><index|/:msg:cadet:local:port:close>
+  message for closing the port.>
+
+  <\explain>
+    (construct-local-data <var|client-channel-number> <var|priority>
+    <var|data>)<index|construct-local-data>
+  </explain|Construct a new 
<scm|/:msg:cadet:local:data><index|/:msg:cadet:local:data>
+  message for sending <var|data> \ <todo|client\<less\>-\<gtr\>service>
+  <todo|to/from> the channel with identifier <var|client-channel-number> at
+  the priority specified by the numeric priority-preference value
+  <var|priority>.>
+
+  <\explain>
+    <scm|(construct-local-acknowledgement
+    <var|client-channel-number>)><index|construct-local-acknowledgement>
+  </explain|Construct a new 
<scm|/:msg:cadet:local:acknowledgement><index|/:msg:cadet:local:acknowledgemeent>
+  message for the channel with identifier <var|client-channel-number>, for
+  informing the client that the service is ready for more data.>
+
+  <\explain>
+    <scm|(construct-local-channel-create <todo|arguments> <var|#:options>)>
+  </explain|Construct a new <scm|msg:cadet:local:channel:create> message for
+  <todo|which direction? client\<less\>-\<gtr\>service, reasonable options>>
+
+  <\explain>
+    (construct-destroy-local-channel <var|client-channel-number>)
+  <|explain>
+    Construct a new <scm|msg:cadet:local:channel:destroy> message to destroy
+    the channel with identifier <var|client-channel-number>. This can be sent
+    in two directions: from the client to the service, to close the channel,
+    or from service to client, to inform the channel has been closed.
+
+    <todo|Can the service send this without the client requesting this? If
+    the client send this message, will the service send this message in
+    return as an acknowledgment?>
+  </explain>
+</body>
+
+<\initial>
+  <\collection>
+    <associate|page-medium|paper>
+    <associate|save-aux|false>
+  </collection>
+</initial>
\ No newline at end of file
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 0f73fd1..2f22bb3 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -7,7 +7,7 @@
   manual>|<doc-author|<author-data|<author-name|Maxime
   Devos>|<author-email|maximedevos@telenet.be>>>>
 
-  Copyright \<#A9\> 2021, 2022 GNUnet e.V.
+  Copyright \<#A9\> 2012-2016, 2021, 2022 GNUnet e.V.
 
   Permission is granted to copy, distribute and/or modify this document under
   the terms of the GNU Free Documentation License, Version 1.3 or any later
@@ -248,6 +248,10 @@
 
   <include|distributed-hash-table.tm>
 
+  <chapter|Communication between peers>
+
+  <include|cadet.tm>
+
   <chapter|Cryptography>
 
   The module <scm|(gnu gnunet crypto)><index|(gnu gnunet crypto)> has a few
diff --git a/doc/service-communication.tm b/doc/service-communication.tm
index 056be14..c3c36a1 100644
--- a/doc/service-communication.tm
+++ b/doc/service-communication.tm
@@ -160,6 +160,58 @@
 
   <todo|how to define new message types>
 
+  <section|Sending messages>
+
+  Messages can be sent with the <scm|send-message!><index|send-message!>
+  procedure, which can be called as <scm|(send-message! <var|mq>
+  <var|message> #:priority <var|priority>)>, where <var|mq> is the message
+  queue and <var|message> is the message to send as a readable bytevector
+  slice. This is an asynchronuous operation, so this procedure can return
+  before the service has processed the message.
+
+  Depending on the transport, it might be possible for messages to be lost or
+  received out-of-order. Some transports allow to explicitely allow messages
+  to be lost or received out-of-order and would by default retransmit lost
+  messages and reorder out-of-order messages; this behaviour can to a degree
+  be controlled by setting the <dfn|priority-preference> flags.
+
+  These flags are not absolute, e.g. even if reliable transmission is
+  requested, it is possible that the transport fail to transmit the message.
+  The exact behaviour is transport-dependent!
+
+  <\description>
+    <item*|<scm|pref:unreliable>>Unreliable delivery is acceptable.
+
+    <item*|<scm|pref:low-latency>>Low latency is desired, this cannot be
+    meaningfully combined with <scm|pref:cork-allowed>.
+
+    <item*|<scm|pref:cork-allowed>>The transmission of a message can be
+    delayed to combine this message with other messages into a larger
+    transmission with less per-message overhead.
+
+    <item*|<scm|pref:good-throughput>>High bandwith is desired; the method
+    chosen for transmission should focus on overall throughput.
+
+    <item*|<scm|pref:out-of-order>>Out-of-order delivery is acceptable.
+  </description>
+
+  These flags can be combined into a numeric value with the macro
+  <scm|prio-prefs> from <scm|(gnu gnunet mq prio-prefs)>; the following code
+  defines <var|x> as the numeric value of the flags <scm|pref:unreliable> and
+  <scm|pref:out-of-order>:
+
+  <\scm>
+    (import (gnu gnunet mq prio-prefs))
+
+    (define x (prio-prefs pref:unreliable pref:out-of-order))
+  </scm>
+
+  This numeric priority-preference can be passsed to <scm|send-message!> as
+  the optional <var|priority> keyword argument of <scm|send-message!>. The
+  transport of <scm|connect/fibers> is always reliable and in-order.
+  <todo|notify-sent! callbacks><todo|cancellation><todo|queue size limits,
+  <scm|%suspicious-length>>
+
   <section|Error handler><index|error handler>
 
   The message queue implementation usually just sends and receives messages,
diff --git a/gnu/gnunet/mq/prio-prefs.scm b/gnu/gnunet/mq/prio-prefs.scm
index a66300f..babcf37 100644
--- a/gnu/gnunet/mq/prio-prefs.scm
+++ b/gnu/gnunet/mq/prio-prefs.scm
@@ -1,5 +1,5 @@
 ;; This file is part of scheme-GNUnet.
-;; Copyright (C) 2012-2016, 2021 GNUnet e.V.
+;; Copyright © 2012-2016, 2021-2022 GNUnet e.V.
 ;;
 ;; scheme-GNUnet is free software: you can redistribute it and/or modify it
 ;; under the terms of the GNU Affero General Public License as published
@@ -23,6 +23,7 @@
 ;; @brief General-purpose message queue (priorities, numeric)
 (library (gnu gnunet mq prio-prefs)
   (export priority-preference priority-preference?
+         prio-prefs
          PRIORITY_MASK
          prio-prefs->integer
          prio-pref:?
@@ -42,6 +43,14 @@ return its numeric value."
       (apply bitwise-ior
             (map (compose (cute expt 2 <>) value->index) values)))
 
+    (define-syntax prio-prefs
+      (syntax-rules ()
+       "Return the numeric value of the priority-preference flags
+@code{pref:x} @code{...}."
+       ((_ pref:x ...)
+        (prio-prefs->integer
+         (symbol-value priority-preference pref:x) ...))))
+
     (define (prio-pref:? integer flag)
       "Is the flag @var{flag} (an enum value) set in
 the integer @var{integer}?"
@@ -63,7 +72,7 @@ enum values.  The priority bits are ignored."
               (bit pref:unreliable
                    pref:low-latency
                    pref:cork-allowed
-                   pref:goodput
+                   pref:good-throughput
                    pref:out-of-order))))
 
     ;; Bit mask to apply to extract the priority bits.
diff --git a/gnu/gnunet/mq/prio-prefs2.scm b/gnu/gnunet/mq/prio-prefs2.scm
index 61def3f..5bc2eb5 100644
--- a/gnu/gnunet/mq/prio-prefs2.scm
+++ b/gnu/gnunet/mq/prio-prefs2.scm
@@ -84,8 +84,7 @@ with other messages into a larger transmission with less
 per-message overhead.")
        (index 6))
        (value
-       (symbol pref:goodput)
-       ;; FIXME maybe rename to pref:good-throughput
+       (symbol pref:good-throughput)
        (documentation
         "Flag to indicate that high bandwidth is desired. This flag
 indicates that the method chosen for transmission should focus on

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.