Request / Response example

[ThomasFreedman]

It's truly great that Mark provides these examples to help get developers up to speed using Reticulum. As developers we all know there's always room for improvement, given the time for it. Here's my constructive input on this example. I offer this from my own myopic perspective, but recognize my suggestion may not be as useful if it were being used with the other examples he provides.

It would be better if the client mode used the announce sent by the server mode to create the destination to send the request back to the server rather than asking for it on the command line.

Since the destination address provided on the command like is for the server (presumably taken from the RNS.log), I see no value in the server code to send an announce, as there is no announce handler to receive it on the client.

Also, since the "Understanding Reticulum" doc states that announces contain everything required to securely reply to the source of the announce, this is a perfect place to showcase that. Here is some suggested code you might consider using. It's not a complete example, it is meant to be used within a class definition:

`
# Create an RNS communications endpoint using the AppName and provided ID
def createRNSdestination(self, rnsID):
return RNS.Destination(rnsID, RNS.Destination.OUT,
RNS.Destination.SINGLE,
self.AppName)

# This method might not be necessary if announcements always come with a
# path to the server. It sends an RNS path request and waits for responses.
# Set a timer and log the failure if no response arrives in MaxRNSwait secs.
# This method only called if a path to the server does NOT exist. It will be
# called periodically from the waitForServerAnnounces loop until a path exists
# or times out.
def checkPathForLink(svr)
    prnt = svr["prnt"]
    if svr["timer"] is None:        # Start a timer
        svr["timer"] = dt.now()
        RNS.log(f"checkPathForLink: No path to {prnt}! Requesting one...")
        RNS.Transport.request_path(pub["dest"])
    else:                           # Check if path exists yet
        svr["path"] = RNS.Transport.has_path(svr["dest"])
        timer = (dt.now() - svr["timer"]).total_seconds()
        if svr["path"]:
            RNS.log(f"checkPathForLink: Got path to {prnt}")
            svr[timer] = None
        elif timer >= self.MaxRNSwait:
            RNS.log(f"checkPathForLink: Path request to {prnt} timed out")
            svr["timer"] = 0  

# Create an encrypted RNS link to a server we can make requests through.
# The linkClosed method can be used to garbage collect the servers when
# the link is no longer required.
def createLinkToServer(self, svr):
    prnt = svr["prnt"]
    if svr["path"]:  # A link requires a path; this only says if it exists
        RNS.log(f"createLinkToServer: Creating a link to {prnt}...")
        link = RNS.Link(svr["dest"], established_callback=self.linkCreated,
                                     closed_callback=self.linkClosed)
        svr["link"] = link
    else: self.checkPathForLink(svr) # Handle the "no path" case

# Method to monitor for announcements and open RNS links. All
# servers and the info obtained here is saved in the Servers dictionary.
def waitForServerAnnounces(self):
    print(f"Waiting for {self.AppName}s. Press ^C to exit")
    svr = None
    while True:
        for server in self.Servers.keys(): # Scan list of Servers
            svr = self.Servers[server]
            if svr["dest"] is None: svr["dest"] = self.createRNSdestination(svr["ID"])
            if svr["link"]  is None: self.createLinkToServer(svr)
        time.sleep(0.2)   # Wait a bit to check for another announcement

# Define an  announce handler class that Reticulum will call when an
# announcement arrives from a server node.  Since this is a callback,
# the work done here is kept to a minimum so impact on RNS is
# minimized. The parent can asynchronusly monitor the length of the
# Server dictionary for new announcements from multiple sources, and
# respond to them appropriately.
class AnnounceHandler:
    # The initialization method takes  the optional aspect_filter argument
    # to limit announcements this handler will process.  The aspect_filter
    # used is self.AppName.  The aspect filter must be specific, no wild-
    # cards are accepted. This must be callable without any parameters.
    def __init__(self, aspect_filter=None, parent=None):
        self.aspect_filter = aspect_filter
        self.parent = parent

    # RNS callback function for anouncements
    def received_announce(self, destination_hash, announced_identity, app_data):
        server = destination_hash
        self.parent.Servers[server] = {}
        svr["ID"]    = announced_identity
        svr["prnt"]  = RNS.prettyhexrep(server)
        svr["time"]  = dt.now().strftime("%Y-%m-%d %H:%M:%S")
        svr["path"]  = RNS.Transport.has_path(server)
        svr["dest"]  = pub["link"] = svr["timer"] = None
        # svr["timer"]  is used to wait for path requests, if no path exists
        RNS.log(f"Server {prnt} announced:\n\t{announced_identity}\n\t{app_data}")

`

[markqvist]

It would be better if the client mode used the announce sent by the server mode to create the destination to send the request back to the server rather than asking for it on the command line.

No, because you cannot expect to the remote destination to send an announce concurrently with your app running. Do not think of an announce as a real-time signalling or communication method.

An announce is the primary way for Reticulum to establish paths in the network, and for distributing necessary cryptographic keys throughout the network.

In addition, an announce can contain a small amount of application data. Again, this should not be used for real-time communication. It is much more efficient and correct to use actual packets to and from the destination.

Since the destination address provided on the command line is for the server (presumably taken from the RNS.log), I see no value in the server code to send an announce, as there is no announce handler to receive it on the client.

Incorrect. The server must send an announce, otherwise nothing can reach it. When an announce is sent from a destination, a path converges to that destination in the entire network, and verifiable cryptographic keys are distributed to the entire network.

If you are only trying these examples out locally (that is, via one shared Reticulum instance, running on the same system), that Reticulum instance will of course know about destinations local to itself, and can resolve them without sending an announce. This is not the case in many other cases.

[ThomasFreedman]

Thank you Mark for your replies here today.

No, because you cannot expect to the remote destination to send an announce concurrently with your app running. >Do not think of an announce as a real-time signalling or communication method.

Ok, I get that the announce functionality is mainly to create a path & spread keys. That one of the most awesome aspects of RNS! Once the announce is detected receivers have all they need to setup a link & carry out further communications, the announce has done it's part.

And thanks on the note about concurrency of the announcer & receiver. Regarding that, I have a limited understanding of the "store & forward" capablities of RNS from using Nomadnet. Does the ability to establish a link rely on concurrency of the server & client or not? I understand there are delays imposed by the architecture, and those can be significant in some network topoloogies.

I can run some experiements using your examples, such as request & response and file transfer to get answers to these questions.

[markqvist]

I understand there are delays imposed by the architecture

There are no delays imposed by the architecture as such. In theory, Reticulum can be as fast or as slow as you want it to be. The current Python reference implementation was written with the goal of being easy to understand, and to serve as a blueprint for other implmentations. As such, speed was the last criteria it was created with in mind. Still, it will run with latencies of a few milliseconds, and happily push around 40mbps when used over fast enough mediums (like Ethernet and WiFi).

And thanks on the note about concurrency of the announcer & receiver. Regarding that, I have a limited understanding of the "store & forward" capablities of RNS from using Nomadnet. Does the ability to establish a link rely on concurrency of the server & client or not?

Reticulum itself does not currently include any store-and-forward functionality directly in its core protocol and API. But the functionality it does provide makes it very easy for higher-layer protocols to implement such functionality. An example of this is LXMF (the messaging protocol that NomadNet and Sideband uses). Since LXMF is built on top of Reticulum it was very easy to implement completely decentralised and distributed store and forward functionality in the system. You can use the LXMF source code as a good example of how to do this.

To establish a link to a Destination, it must be available on the network somewhere. The initiator is, per definition, available, since it is the one trying to establish the link.

When LXMF tries to send a message to a recipient, and discovers that it isn't reachable, it uses the distributed encrypted storage to hold the message for the destination, until it becomes available on the network again. The original sender can disappear in the meantime, and does not need to be available at the time of delivery.

[ThomasFreedman]

Well, I sure had that backwards! I was thinking LXMF was the low level & RNS on top of that.

To establish a link to a Destination, it must be available on the network somewhere.

Had you said "online" rather than "available" I'd have gotten the point sooner, which is yes, they must be running concurrently to setup a link.

And thanks for the lesson on object properties. It very much reminds me of the same thing in Javascript.

Ok, so RNS has no store & forward. Going back to announce, I understand your intent, and what you said about many responses to it hitting the app all at once. However, the advantages for using it as a periodic broadcast for my app can't be overlooked.

1. Each instance of the app will send announcements at regularly spaced intervals starting from a randomized offset of seconds with the hour. The extra app data they contain will always be less than 120 bytes.

2. The number of instances of this app is not likely to grow so large they will be difficult for the receiver / link initiator to handle.

3. IPFS relies on the Internet, so my app will use a TCP/IP connection for RNS. As such, different ports can be used to provide some degree of isolation between RNS network segments to facilitate growth.

4. I discovered that even if the same ID is used to create destinations, their addresses are created unique, and cannot be relied upon as a constant. That imposes the need to communicate each one used for the different functions they represent to the link initiator, and to manage their setup and teardown dynamically.

5. If the announcer is not available when the receiver attempts to create a link, the link will timeout/fail and the connection will be attempted at the next announce. Once the link is established the announce & link initiator can sync their state.

6. My app cannot use RNS if it takes hours or days for the announce to propagate between announcer & responder. I recognize the amount of time it takes for the announce to reach a responder is variable and dependent on the network topology when the announcement is made. The purpose of the app is to coordinate people publishing content on IPFS with services that will distribute that content to various platforms. The role of RNS is to provide information about the status of the distribution process.

1. Announcing availability (of content on IPFS)
2. Content Distributor as pinned the content on their IPFS server
3. Distributor has queued content items for distribution
4. Distributor has published an item on a platform
5. Distributor has completed distribution on all target platforms

Communication doesn't have to be real time, but the closer to real time the better. If a publisher produces new content every day, and it takes the distributor hours to complete the distribution to every platform, it may require several link sessions to convey the status of the process before state 5 is reached.

A similar use of RNS came to mind for the Pirate Box. If a PBox user elects to make their curated content available to others, they could announce it the same way a publisher does. The announcement contains the IPFS address of the SQLite catalog, which contains the IPFS hashes of metadata and media files. That use of RNS is actually cleaner, and doesn't require any links at all. PBoxes can browse the announcements or open the query tool I created to search for content or content publishers of interest. It's all on IPFS, and their PBox eliminates the need to use the centralized gateways.

I was hoping to use YaCy to decentralize searching the curated content on PBoxes, but that proved to be too time consuming for me to do.

[ThomasFreedman]

I thought I came up with a way to use the intended design pattern for destinations, but as I was debugging it I realized every destination requires a new link and / or new resources.

That is way more overhead than is necessary when one link and a few message types will do. Any type of filtering or paths for routing messages require a new destination, which in turn requires a new link, if links & resources are to be used. I will instead use a single destination and link and simply use a few bytes of data to route the message to an appropriate handler as I previously described.

The way I see it using more destinations, links & resources just increases the chances of failure and complicates the communications. But since I'm new to using RNS and biased given my history with TCP/IP, I'm open to alternative perspectives.

[markqvist]

Maybe it would be a good idea to post a general description of the application you are writing, and the current architecture. It sounds like there may be room for a few improvements here :)

[ThomasFreedman]

As I described above, the purpose of the app is to coordinate people publishing content on IPFS with services that will distribute that content to various platforms. The role of RNS is to provide information about the status of the distribution process. Here are the general states a particular media item will go thru, after is is created by publisher:

1. Announcing availability (of content on IPFS)
2. Content Distributor as pinned the content on their IPFS server
3. Distributor has queued content items for distribution
4. Distributor has published an item on a platform
5. Distributor has completed distribution on all target platforms

Communication doesn't have to be real time, but the closer to real time the better for the publisher's UX. If a publisher produces new content every day, and it takes the distributor hours to complete the distribution to every platform, it may require several link sessions to convey the status of the process before state 5 is reached.

RNS will be used to inform the publisher of the distribution process as it goes thru those 5 states.
That's a pretty good overview.

[markqvist]

I don't know whether all participants in the system are homogenous in terms of function and activities. But either way, I think it should be possible for all participants to simply use two different destination types - one for publisher and one for those running IPFS nodes - that other participants can communicate with.

• Each participant can keep a list of relevant other endpoints in the network, according to what they need to do. This list gets updated by receiving announces from other nodes. Set up an announce handler to receive events.
• After being on the network for a little time, a publisher knows a good amount of IPFS node operators (distributors) from listening for announces.
• Each time the publisher wants to publish something, they can select the most suitable subset of distributors from their list, and send requests to those for pinning their content. The publisher receives an acknowledgement or denial message from the distributor as a response to their content pinning request.
• When a content pinning request has been accepted by a distributor, the publisher waits for a notification from the distributor that the content has been sucessfully pinned.
• The publisher keeps track of how many distributors have successfully pinned their content, and stops asking more distributors to pin it, once a target distribution level has been reached.

You could create the yourapp.publisher and yourapp.distributor destination types in your application. Each announce their availability on the network, which serves to facilitate global distributor service discovery. Publishers are also discovered, but for the basic purpose that distributors can send service notifications back to them.

You let each publisher handle it's own knowledge of the content distributors on the network, and let each instance handle it's own logic for which to choose for pinning requests. There should be no central consensus. Take a look at the LXMF source code for ideas on how to do this.

This way your application becomes truly decentralised, distributed and efficient. Bandwidth requirements for the above architecture are extremely low. The application would tolerate nodes dropping in and out. No central bootstrap is required. A nice system :)

[ThomasFreedman]

That's very similar to what I have in mind. We agree only 1 destination is necessary per node, which seems to differ from the model where messages are routed / filtered per function as in the list of states I mentioned.

You also see how well announces fit into this application. Although currently the way they are handled differs from what you describe, that doesn't preclude it being more generalized later. I am implementing this with one particular distributor in mind now, but I intend the system to involve the entire Pirate Box network which will more closely resemble your description.