scheme-gnunet

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).