Add readme

README.org

@@ -0,0 +1,52 @@
+* 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 [[https://gitlab.com/spritely/guile-goblins/-/blob/main/examples/prelay-server.scm][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.
+ #+BEGIN_SRC bash
+   guix shell guile goblins
+ #+END_SRC
+**** Option 1: localhost-only for testing
+On your machine, run the script with arguments to create a new tcp relay.
+ #+BEGIN_SRC bash
+   guile prelay-server.scm new-relay tcp-tls
+ #+END_SRC
+**** 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.
+ #+BEGIN_SRC bash
+   guile prelay-server.scm new-relay tcp-tls example.com 69420
+ #+END_SRC
+
+**** Admin sturdyref
+Once it's running it should give you an ocapn sturdyref URI that looks like
+ #+BEGIN_SRC
+ocapn://lm3diirygy3timbrmvrteytdgvqtmobxge4gcmbwgrrdcntgmzrtknrygfrtqobqmuydkojqmizwmmrwgrtdgzjyme4gkmrvgvtdamtegaydenzhorrxallunrztgmr2yg36awawsxz5gkuoi5t42cc2nxhiz7sxzlfdkfwyk3al3rposhev2.prelay/s/ksmG0sFM-xgypoY7LlJlYNMuDojc-vifcRJxR6AC3P0?host=localhost&port=42069
+ #+END_SRC
+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.
+ #+BEGIN_SRC bash
+   guile prelay-server.scm add-account <admin-sturdyref> username1/chat
+   guile prelay-server.scm add-account <admin-sturdyref> username2/chat
+ #+END_SRC
+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:
+ #+BEGIN_SRC bash
+   guile goblin-echo.scm listen <username1-sturdyref>
+ #+END_SRC
+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:
+ #+BEGIN_SRC bash
+   guile goblin-echo.scm say <username2-sturdyref> <say-port-sturdyref> "Hello there!"
+ #+END_SRC
+Again, this can only be done once per account at the moment, since src_bash{<username2-sturdyref>} is a one-time account creation link.
+*** Done!
+The listener should see the message printed in their terminal!