Since using I2P for a few years, and dealing with SAM and all it's problems I realized very quickly that something different was needed. This is what I came up with.

Separate the commands from the data channels. To do this, Two things are needed:

One, an application command channel socket to router.

Two, the application data sockets to/from router that carry only data.

The command channel is only needed for making or setting the initial destination key, and to set the destination key to port bindings. That is how SAM should have been done in the first place, but was not! :-)

Note that YOUR application holds the keypair values, NOT the router. This is to reduce any extra complexity in the router code.

KEYS = keypair public+private, these are BASE64

KEY = public key, BASE64

ERROR as is implied returns the message "ERROR "+DESCRIPTION+"\n", where the DESCRIPTION is what went wrong.

OK returns "OK", and if data is to be returned, it is on the same line. OK means the command is finished.

DATA lines contain information that you requested. There may be multiple DATA lines per request.

NOTE: The help command is the ONLY command that has an exception to the rules... it can actually return nothing! This is intentional, since help is a HUMAN and not an APPLICATION command.

For CURRENT details on the commands PLEASE use the built-in help command. Here are the commands we have as of this writing (Dec 2008).

COMMAND		OPERAND					RETURNS
help		(optional command to get help on)	NOTHING or OK and description of the command
clear							ERROR or OK
getdest							ERROR or OK and KEY
getkeys							ERROR or OK and KEYS
getnick		tunnelname				ERROR or OK
inhost		hostname or IP address			ERROR or OK
inport		port number				ERROR or OK
list 							ERROR or DATA lines and final OK
newkeys 						ERROR or OK and KEY
option 							ERROR or OK
outhost 	hostname or IP address			ERROR or OK
outport 	port number				ERROR or OK
quiet 							ERROR or OK
quit 							OK and terminates the command connection
setkeys 	KEYS					ERROR or OK
setnick 	tunnel nickname				ERROR or OK
show 							ERROR or OK and information
start 							ERROR or OK
status 		tunnel nickname				ERROR or OK and information
stop 							ERROR or OK
verify		KEY					ERROR or OK

Once set up, all TCP sockets can and will block as needed, and there is no need for any additional messages to/from the command channel. This allows the router to pace the stream without exploding with OOM like SAM does as it chokes on attempting to shove many streams in or out one socket -- that can't scale when you have alot of connections!

What is also nice about this particular interface is that writing anything to interface to it, is much much easier than SAM. There is no other processing to do after the set up. It's configuration is so simple, that very simple tools, such as nc (netcat) can be used to point to some application. The value there is that one could schedule up and down times for an application, and not have to change the application to do that, or to even have to stop that application. Instead, you can litterally "unplug" the destination, and "plug it in" again. As long as the same IP/port addresses and destination keys are used when bringing the bridge up, the normal TCP application won't care, and won't notice. It will simply be fooled -- the destinations are not reachable, and that nothing is coming in.

For the following example, we'll setup a very simple local loopback connection, with two destinations. Destination "bitch" will be the CHARGEN service from the INET superserver daemon. Destination "ear" will be a local port that you can telnet into, and watch the pretty ASCII test puke forth.

EXAMPLE SESSION DIALOGUE -- simple telnet 127.0.0.1 2827 works
A = Application
C = BOB's Command response.

FROM 	TO	DIALOGUE
A	C	setnick bitch
C	A	OK Nickname set to bitch
A	C	newkeys
C	A	OK ZMPz1zinTdy3~zGD~f3g9aikZTipujEvvXOEyYfq4Su-mNKerqG710hFbkR6P-xkouVyNQsqWLI8c6ngnkSwGdUfM7hGccqBYDjIubTrlr~0g2-l0vM7Y8nSqtFrSdMw~pyufXZ0Ys3NqUSb8NuZXpiH2lCCkFG21QPRVfKBGwvvyDVU~hPVfBHuR8vkd5x0teMXGGmiTzdB96DuNRWayM0y8vkP-1KJiPFxKjOXULjuXhLmINIOYn39bQprq~dAtNALoBgd-waZedYgFLvwHDCc9Gui8Cpp41EihlYGNW0cu0vhNFUN79N4DEpO7AtJyrSu5ZjFTAGjLw~lOvhyO2NwQ4RiC4UCKSuM70Fz0BFKTJquIjUNkQ8pBPBYvJRRlRG9HjAcSqAMckC3pvKKlcTJJBAE8GqexV7rdCCIsnasJXle-6DoWrDkY1s1KNbEVH6i1iUEtmFr2IHTpPeFCyWfZ581CAFNRbbUs-MmnZu1tXAYF7I2-oXTH2hXoxCGAAAA

MAKE NOTE OF THE ABOVE DESTINATION KEY, YOURS WILL BE DIFFERENT!

FROM 	TO	DIALOGUE
A	C	outhost 127.0.0.1
C	A	OK outhost set
A	C	outport 19
C	A	OK outbound port set
A	C	start
C	A	OK tunnel starting

At this point, there was no error, a destination with a nickname of "bitch" is set up. When you contact the destination provided, you actually connect to the CHARGEN service on 19/TCP.

Now for the other half, so that we can actually contact this destination.

FROM 	TO	DIALOGUE
A	C	setnick ear
C	A	OK Nickname set to ear
A	C	newkeys
C	A	OK 8SlWuZ6QNKHPZ8KLUlExLwtglhizZ7TG19T7VwN25AbLPsoxW0fgLY8drcH0r8Klg~3eXtL-7S-qU-wdP-6VF~ulWCWtDMn5UaPDCZytdGPni9pK9l1Oudqd2lGhLA4DeQ0QRKU9Z1ESqejAIFZ9rjKdij8UQ4amuLEyoI0GYs2J~flAvF4wrbF-LfVpMdg~tjtns6fA~EAAM1C4AFGId9RTGot6wwmbVmKKFUbbSmqdHgE6x8-xtqjeU80osyzeN7Jr7S7XO1bivxEDnhIjvMvR9sVNC81f1CsVGzW8AVNX5msEudLEggpbcjynoi-968tDLdvb-CtablzwkWBOhSwhHIXbbDEm0Zlw17qKZw4rzpsJzQg5zbGmGoPgrSD80FyMdTCG0-f~dzoRCapAGDDTTnvjXuLrZ-vN-orT~HIVYoHV7An6t6whgiSXNqeEFq9j52G95MhYIfXQ79pO9mcJtV3sfea6aGkMzqmCP3aikwf4G3y0RVbcPcNMQetDAAAA
A	C	inhost 127.0.0.1
C	A	OK inhost set
A	C	inport 37337
C	A	OK inbound port set
A	C	start
C	A	OK tunnel starting
A	C	quit
C	A	OK Bye!

Now all we need to do is telnet into 127.0.0.1, port 37337, send the destination key or host address from addressbook we want to contact. In this case, we want to contact "bitch", all we do is paste in the key and it goes.

NOTE: The "quit" command in the command channel does NOT disconnect the tunnels like SAM.

# telnet 127.0.0.1 37337
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
ZMPz1zinTdy3~zGD~f3g9aikZTipujEvvXOEyYfq4Su-mNKerqG710hFbkR6P-xkouVyNQsqWLI8c6ngnkSwGdUfM7hGccqBYDjIubTrlr~0g2-l0vM7Y8nSqtFrSdMw~pyufXZ0Ys3NqUSb8NuZXpiH2lCCkFG21QPRVfKBGwvvyDVU~hPVfBHuR8vkd5x0teMXGGmiTzdB96DuNRWayM0y8vkP-1KJiPFxKjOXULjuXhLmINIOYn39bQprq~dAtNALoBgd-waZedYgFLvwHDCc9Gui8Cpp41EihlYGNW0cu0vhNFUN79N4DEpO7AtJyrSu5ZjFTAGjLw~lOvhyO2NwQ4RiC4UCKSuM70Fz0BFKTJquIjUNkQ8pBPBYvJRRlRG9HjAcSqAMckC3pvKKlcTJJBAE8GqexV7rdCCIsnasJXle-6DoWrDkY1s1KNbEVH6i1iUEtmFr2IHTpPeFCyWfZ581CAFNRbbUs-MmnZu1tXAYF7I2-oXTH2hXoxCGAAAA
 !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefg
!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefgh
"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghi
#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghij
$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijk
...
After a few virtual miles of this spew, press Control-]
...
cdefghijklmnopqrstuvwxyz{|}~ !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJK
defghijklmnopqrstuvwxyz{|}~ !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKL
efghijklmnopqrstuvwxyz{|}~ !"#$%&'()*+,-./0123456789:;<=
telnet> c
Connection closed.



Here is what happened...
telnet -> ear -> i2p -> bitch -> chargen -.
telnet <- ear <- i2p <- bitch <-----------'

You can connect to EEPSITES too!

# telnet 127.0.0.1 37337
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
i2host.i2p
GET / HTTP/1.1

HTTP/1.1 200 OK
Date: Fri, 05 Dec 2008 14:20:28 GMT
Connection: close
Content-Type: text/html
Content-Length: 3946
Last-Modified: Fri, 05 Dec 2008 10:33:36 GMT
Accept-Ranges: bytes

<html>
<head>
  <title>I2HOST</title>
  <link rel="shortcut icon" href="favicon.ico">
</head>
...
<a href="http://sponge.i2p/">--Sponge.</a></pre>
<img src="/counter.gif" alt="!@^7A76Z!#(*&amp;%"> visitors. </body>
</html>
Connection closed by foreign host.
#

Pretty cool isn't it? Try some other well known EEPSITES if you like, nonexistant ones, etc, to get a feel for what kind of output to expect in different situations. For the most part, I suggest that you ignore any of the error messages. They would be meaningless to the application, and are only presented for human debugging.

Let's put down our destinations now that we are all done with them.

First, lets see what destination nicknames we have.

FROM 	TO	DIALOGUE
A	C	list
C	A	DATA NICKNAME: bitch STARTING: false RUNNING: true STOPPING: false KEYS: true QUIET: false INPORT: not_set INHOST: localhost OUTPORT: 19 OUTHOST: 127.0.0.1
C	A	DATA NICKNAME: ear STARTING: false RUNNING: true STOPPING: false KEYS: true QUIET: false INPORT: 37337 INHOST: 127.0.0.1 OUTPORT: not_set OUTHOST: localhost
C	A	OK Listing done

Allright, there they are. First, let's remove "bitch".

FROM 	TO	DIALOGUE
A	C	getnick bitch
C	A	OK Nickname set to bitch
A	C	stop
C	A	OK tunnel stopping
A	C	clear
C	A	OK cleared

Now to remove "ear", note that this is what happens when you type too fast, and shows you what typical ERROR messages looks like.

FROM 	TO	DIALOGUE
A	C	getnick ear
C	A	OK Nickname set to ear
A	C	stop
C	A	OK tunnel stopping
A	C	clear
C	A	ERROR tunnel is active
A	C	clear
C	A	OK cleared
A	C	quit
C	A	OK Bye!

I won't bother to show an example of the receiver end of a bridge because it is very simple. There are two possible settings for it, and it is toggled with the "quiet" command.

The default is NOT quiet, and the first data to come into your listening socket is the destination that is making the contact. It is a single line consisting of the BASE64 address followed by a newline. Everything after that is for the application to actually consume.

In quiet mode, think of it as a regular internet connection. No extra data comes in at all. It's just as if you are plain connected to the regular internet. This mode allows a form of transparency much like is available on the router console tunnel settings pages, so that you can use BOB to point a destination at a web server, for example, and you would not have to modify the web server at all.

The advantage with using BOB for this is as discussed previously. You could schedule random uptimes, etc for the application, redirect to a different machine, etc. One use of this may be something like wanting to try to goof up router-to-destination upness guessing. You could stop and start the destination with a totally different process to make random up and down times on services. That way you would only be stopping the ability to contact such a service, and not have to bother shutting it down and restarting it. You could redirect and point to a different machine on your lan while you do updates, or point to a set of backup machines depending on what is running, etc, etc. Only your imagination limits what you could do.

I realize that this really isn't looking like a full blown "API spec", however it's so simple that this is really, honestly, the entire API. The "PROTOCOL" is quite tiny, and there are only Three possible replies to the commands.