• Goblins Echo
  • Usage
    • Setting up the Prelay
      • Option 1: localhost-only for testing
      • Option 2: Public internet relay for using on the web!
      • Admin sturdyref
    • Creating two user accounts
    • Creating the listener
    • Creating a sender
    • Done!

Goblins Echo

This is a simple little app that transmits a message over Goblins using the prelay netlayer.

Usage

To use, a bit of ceremony is currently required! When we have more robust tools, such as a Relay management panel, it should become far easier.

Setting up the Prelay

Fetch the Prelay Server example code. We will use this as our prelay server for now. Then set up a Guix environment (e.g. a shell) with both guile and guile-goblins installed.

  guix shell guile guile-goblins

Option 1: localhost-only for testing

On your machine, run the script with arguments to create a new tcp relay.

  guile prelay-server.scm new-relay tcp-tls

Option 2: Public internet relay for using on the web!

On a public-facing server that has guile/goblins and a copy of the script, run the script with arguments to create a new tcp relay. Include the domain and port you want to listen on.

  guile prelay-server.scm new-relay tcp-tls example.com 69420

Admin sturdyref

Once it's running it should give you an ocapn sturdyref URI that looks like

ocapn://lm3diirygy3timbrmvrteytdgvqtmobxge4gcmbwgrrdcntgmzrtknrygfrtqobqmuydkojqmizwmmrwgrtdgzjyme4gkmrvgvtdamtegaydenzhorrxallunrztgmr2yg36awawsxz5gkuoi5t42cc2nxhiz7sxzlfdkfwyk3al3rposhev2.prelay/s/ksmG0sFM-xgypoY7LlJlYNMuDojc-vifcRJxR6AC3P0?host=localhost&port=42069

This is a "sturdyref" - a reference to an object as text, that can be resolved to a far object in Goblins. Keep this sturdyref around and don't share it, as it gives you the keys to the Prelay.

NOTE: This is not saved across runs, so keep the prelay running as long as you want to do this test, or else you'll have to do this all over again

Creating two user accounts

Now you can go back to a local machine, since you have the sturdyref and can communicate online with the Prelay over goblins/ocapn. Locally on your machine with goblins installed, run the following prelay-server command twice to create two accounts, which will be our listener and our sender accounts.

  guile prelay-server.scm add-account <admin-sturdyref> username1/chat
  guile prelay-server.scm add-account <admin-sturdyref> username2/chat

This will give you two more sturdyrefs representing accounts on the Prelay. These should be passed to the users who wish to communicate (send them over some secure method like Signal or Matrix or just copy-pasting!). They shouldn't share these with anyone else.

These are one-time account logins. Think of them like those links you get in emails when signing up for a service. They can only be used once. Consequently this means with goblins-echo you can only send a single messsage per account, but that'll change later when we switch to a REPL-style chat and keep the reference to the send capability in memory.

Creating the listener

The listener is the one receiving the messages. Now we finally can use our goblin-echo script to create a listener! One of the users can run:

  guile goblin-echo.scm listen <username1-sturdyref>

The listener makes one last sturdyref which represents the port where the messages are sent to! Then they can send this to any user who wants to send them a message

Creating a sender

The sender then runs goblin-echo to say something, with their sturdyref to the prelay, and the sturdyref they got from their peer:

  guile goblin-echo.scm say <username2-sturdyref> <say-port-sturdyref> "Hello there!"

Again, this can only be done once per account at the moment, since

<username2-sturdyref>

is a one-time account creation link.

Done!

The listener should see the message printed in their terminal!