A partial Scheme port of GNUnet, for use in disarchive and Guix (but potentially useful elsewhere as well) TODO: ask upstream if they are OK with the name (upstream has guile-gnunet bindings)

Maxime Devos b4055a1612 doc: Update ROADMAP.org. 3 hours ago
.reuse a55f5139df New module: (gnu gnunet directory) 5 months ago
LICENSES 1b1994e769 Define libextractor metatypes 5 months ago
build-aux 064d99d42a Write code for message handlers 2 months ago
doc 3d63ba8b20 include some notes on reverse-engineering GNUdirs 3 months ago
gnu adde7fd531 config: value-parser: Parse values in configuration files. 6 hours ago
tests 3960e791ee tets: message-handler: Correct imports. 5 hours ago
.gitignore 43191c8cf9 vc: add most build artifacts to .gitignore 2 months ago
.mailmap 63a03a46d1 Change e-mail address 2 months ago
Makefile.am adde7fd531 config: value-parser: Parse values in configuration files. 6 hours ago
README.org d58d0e9b3c doc: Classify modules. 5 hours ago
ROADMAP.org b4055a1612 doc: Update ROADMAP.org. 3 hours ago
configure.ac 7bad3451f8 build: add autotools scripts 2 months ago
guix.scm af805a6741 guix: Add guile-quickcheck dependency. 3 weeks ago

README.org

scheme-GNUnet: a partial Scheme port of GNUnet

How to build & install

TODO: ask upstream of use of name is acceptable TODO: more bindings, less duplication TODO: document directory & meta data format #+BEGIN_SRC shell # When using Guix # (XXX make dependency on Guix itself optional) guix environment -l guix.scm

things that work

autoreconf -vif ./configure make make check #+END_SRC TODO install TODO: test suite for download & publish. TODO (elsewhere): GNUnet service definitions for Guix in container

DONE publishing store items

(Script: gnu/gnunet/scripts/publish-store.scm) (Described in ROADMAP.org)

DONE downloading store items

We cheat by calling the gnunet-publish binary. Use this to publish a directory from the store! (Script: gnu/gnunet/scripts/download-store.scm) (Described in ROADMAP.org)

Purposes

Modules

Tags

    The inverse of the former, to be implemented. When implemented, contact guix-devel on how to proceed. Either creates a directory structure or a nar.
  • for use by Guix and disarchive
  • bit-for-bit reproducibility in directory creation
  • a nice Scheme interface to GNUnet!
  • gnu/gnunet/directory.scm: directory construction
  • gnu/gnunet/message/envelope.scm: some program data around
  • message types (e.g. priority, notify-on-sent)
  • gnu/gnunet/concurrency/update.scm: a box with a value,
  • that can be updated, resulting in a new box. Updates can be waited upon.
  • gnu/gnunet/utils/platform-enum.scm: Platform-specific
  • C-style enum values.
  • spec: it is unknown if this will turn out to be a practical abstraction.
  • why: it remains to be seen if these modules will have any use
  • test: these modules have (passing) tests
  • good: these modules, abstractions ... are practical, and will not be scrapped
  • (tweaks might still be possible, and the modules could still have missing functionality)
  • wart: these modules have some ‘unniceties’ (warts). This does not prevent
  • the ‘good’ tag.

Message queues spec

Message queues have three parts: the input queue, the output queue and the transport, that are respectively a read+close request capability, a write+close request capability and a capability for all the previous, reacting to a close request and injecting errors.

  • gnu/gnunet/mq/prio-prefs.scm: message priorities & preferences
    Preferences: is out-of-order allowed or not, should the message be corked or not ...
  • gnu/gnunet/mq/handler.scm: what to do in
  • response to a message.

Configuration test good

    Different message types may need need different capabilities; the interposition can be used to adjust the ambient authority appropriately.
  • gnu/gnunet/mq/message-io.scm: like soft ports, but using
  • fibers channels and for messages.
  • TODO actual queues? Maybe we don't need them?
  • TODO filling the queues
  • gnu/gnunet/config/parser.scm: Parse configuration files.
  • gnu/gnunet/config/expand.scm: Perform variable expansion.
  • gnu/gnunet/config/value-parser.scm: Parse configuration values.
  • TODO: value->data, value->relative-time

Network structures good wart

TODO: writing, modifying, querying ... Features:

  • structures are always architecture-independent
  • (no possible dependencies on the C ABI)
  • big / little endianness distinction
  • (almost) no runtime overhead over raw
  • slice-u8-ref & friends when using syntax API
    (Some overhead is incurred due to type-checking) TODO: verify expanded code
  • structures can have various meta data
  • (e.g. docstring) TODO write emacs functions for looking up docstrings etc.
    Not features (in contrast with scheme-bytestructures):
  • not extensible with new kinds of network structure types.
    How to use:
  • define network structures in a (... struct) module
  • using (gnu gnunet netstruct syntactic) or (gnu gnunet netstruct procedural)
  • use network structures outside the (... struct) module
  • using (gnu gnunet netstruct syntactic) or (gnu gnunet netstruct procedural) module.

The former is preferred as offsets and sizes etc. are inlined

GNUnet network structures good

More refined IP, TCP, UDP, ... test good why

    TODO: make sure no references to (... struct) modules are created when accessing network structures with (gnu gnunet netstruct syntactic).
  • gnu/gnunet/nse/struct.scm: network size estimation
  • gnu/gnunet/hashcode/struct.scm: hashes
  • gnu/gnunet/crypto/struct.scm: signatures, keys, nonces ...
  • gnu/gnunet/util/struct.scm: various things
  • gnu/gnunet/icmp/struct.scm: ICMP packet types & codes
  • (incomplete, to be used for error messages)
  • gnu/gnunet/util/cmsg.scm: Constructing & analysing
  • ancillary messages (likewise)

Conventions

Fibers, capabilities and ambient authority

TODO: IP_PKTINFO for interface address, scope ... TODO: message queue based upon this TODO: nice abstraction for network errors Modules are expected to use ‘fibers’ for concurrency.

They should not introduce any ambient authority, and avoid implicit use of pre-existing ambient authority (e.g. current-output-port, the current persona).

Documenting modules

Fiddling with options

Tests

To avoid accidental reuse of capabilities accross modules, do not call callbacks where it can be avoided. Consider conditions for signalling an event occurred instead. Add a little information to ‘* Modules’. Options like ‘priority’, ‘anonymity’, ‘replication’ and ‘no-index’ should be ‘passed’ using SRFI-39 parameters, and not with positional or keyword arguments, as they are just passed through unchanged most of the time. Read --> How SQLite Is Tested (accessed: 2021)

This GNUnet implementation isn't quite that well-tested, and most likely won't be for the foreseeable future. However, when defining new code, try to define the following kind of tests where reasonable (non-exhaustive);

  • verify (iso-)morphisms and similar properties are upheld (e.g.
  • using guile-quickcheck for generating test cases). E.g. if there is a conversion function f : X -> Y and g : Y -> X, verify (compose f g) = id = (compose g f). Verify morphisms like (length (append x y)) = length (x) + length (y).
  • Run mutation tests! That is, replace < with <=, 0 by 1, a variable
  • reference ‘i’ by a variable reference ‘j’, swap destination and source arguments ... and verify whether the tests catch these little mutations!
  • Verify argument checking!
  • (basic non-dependent type checking, in-bounds, right capabilities ..., appropriate exception). An &assertion is usually fine, though occassionally a more informative condition may be in-place.

Wishlist

  • Schemification
    Many procedures are less-or-more directly transcribed from the imperative C source code. Less is preferred over more.
  • Less copying bytevectors around

License

Contact

Bytevectors are often duplicated to preserve safety in presence of buggy / insecure / hostile code in a sandbox. See the LICENSES directory for license text, and each file with source code for the license and copyright text. Most code is under the Affero General Public License (v3 or later), see each source file for details. Maintainer: Maxime Devos . PGP fingerprint: C1F3 3EE2 0C52 8FDB 7DD7 011F 49E3 EE22 1917 25EE. Patches may be sent as formatted by `git format-patch`. E-mail messages should ideally by be signed with PGP (or GnuPG, etc.).

Presuming I'm using the word ‘notoriously’ correctly, announcements by the maintainer of ‘taking a break’ from Guix+GNUnet hacking are notoriously unreliable. I suggest you disregard them (but note that sometimes these are actually true).