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
# When using Guix
# (XXX make dependency on Guix itself optional)
guix environment -l guix.scm
things that work
TODO: test suite for download & publish.
TODO (elsewhere): GNUnet service definitions for Guix in container
DONE publishing store items
(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!
(Described in ROADMAP.org)
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
- 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 ...
- 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.
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)
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).
Fiddling with options
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.
Many procedures are less-or-more directly transcribed
from the imperative C source code. Less is preferred over
- Less copying bytevectors around
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