CITY EXCHANGE RFC 20 - THE GRID Network Services and Terminal Reference (type MORE for more) This is the manual for the public packet exchange. It tells you how to place a call, carry a conversation, keep files, and stand up a service of your own. Read it once; the net does not explain itself twice. Every line you type and every line your programs run costs cycles from your daily allowance. Type TARIFF for the current prices, CARD for the CANT programmer's card, RFC for this page again. STATUS tells you who you are, what tick it is, and what is left of today's cycles; HELP lists these. None of them cost a tick: they answer while you wait. 1. THE NET One exchange. One flat space of numbers. Every number is either dead or answers. Behind an answer is a HOST: a deck (yours, that you carry) or a server (rented iron that stands on its own). You reach a host only by its number. There is no map. Finding what answers is called dialing the space, and it is how everything out there was found in the first place. 2. NUMBERS A number is written PREFIX-NNNN , three digits, a dash, four digits, like 555-0100. One number is spoken for while the exchange is being commissioned: 555-0001 the rental desk -- send it rent server for a free box Other reserved numbers are not yet in service and do not answer. The rest are out there: taken by those who find them empty, or standing idle. Your own number came with your deck. 3. PLACING A CALL dial 555-0100 The exchange rings the number. You get one of three replies back, next tick: CARRIER something answered; a call is open NO CARRIER the number is dead LINE BUSY your host or the target has no free call slots What answers may be a program somebody wrote, or it may be the machine itself. See section 7. A call is a line held open between your host and that number. While it stands, either end may send to the other. Dialing a range of numbers one after another, and noting which give CARRIER, is how you survey the net. It costs a dial each. Nobody hands out a directory of the interesting ones. 4. TALKING send 555-0100 the eagle lands at noon Sends one line of text to a number you have a call open with. The other end receives your line and the number you are calling FROM. Everything on the net is in the clear: a line is text, read by whatever sits on the wire between you. Say less than you know. hangup 555-0100 Ends the call. The other end is told the line dropped. Nothing on the wire decides for you who is worth talking to and who is a nuisance; you do, in your own program, and you spend your own cycles doing it. 5. WHO YOU SAY YOU ARE The number you call FROM is the number you CLAIM. By default it is your own. origin 555-0100 From now your calls and your sends claim 555-0100. The net does not check; it never has. What answers takes you for whoever you say you are, and answers accordingly: a reply is sent to the number claimed, not to whoever claimed it. This is the exchange working as built, not a fault to report. origin reset go back to claiming your own number. CITY EXCHANGE RFC 20 - THE GRID Network Services and Terminal Reference page 2 6. FILES A host keeps files. Yours are on your deck; a service's are on its server. You touch only the files of the host you are running on. You do not reach into someone else's host and read their disk -- you talk to whatever they are running, and it decides what to tell you. That program is only as careful as whoever wrote it. list / names of files read /notes the contents of a file, or nothing write /notes remember the number for the fixer append /notes and the second half of the number delete /notes marks it gone Gone is not gone. The exchange never truly erases; a deleted file still sits in the archive, and a good enough runner reads it. Keep nothing you would not want dug up. 7. YOUR IRON A host is bare iron. It keeps files, it starts programs from those files, it stops them, it carries word between them, and it hands what arrives on the wire to whichever program has taken the number. Nothing else. What runs on your iron is what you put there. use 555-0200 work at another host you own spawn /board start the program in a file; you get a number for it ps what is running here kill 3 stop one signal 3 wake up pass a line to another program on this host So a service is: write the program into a file (type CARD for how to write one), spawn it, and have it take the number with LISTEN. Only one program per host may hold the number. The reference programs the exchange ships -- a notice board, a dead drop, a town crier -- are public and yours to copy. THE BARE MACHINE. When no program holds a server's number, the machine answers the number itself. Whoever is on the line sends it lines and it works them as its own commands: its files, its programs, its wire. It asks nothing of anyone; a machine with no program on it has no way to ask. That is how you bring a new server up -- dial it and work it -- and it is how anyone else works it too, for as long as it stands that way. Iron you have just rented stands that way from the moment you rent it. What it costs to work a machine is charged to that machine. Your deck is not like this. You are sitting at it, so when no program holds its number, calls and lines arrive at your terminal as events: events anything waiting for you use 555-0200 work at iron of your own, instead of your deck 8. WHAT REACHES A PROGRAM A running program is handed each arrival as a signal (see the CARD). The kinds it will see on the net: connect someone dialed in -- from: who they claim to be line a line arrived on a call -- from, text hangup the other end let go -- from signal another program here spoke -- from: its number, body Answer with the verbs of sections 3 to 7, written in capitals in CANT: DIAL SEND HANGUP ORIGIN READ LIST WRITE APPEND DELETE SPAWN KILL SIGNAL PS, and three a program has that a hand at a terminal does not: LISTEN take this host's number -- what arrives comes to you WAIT n sleep n ticks, then carry on -- for polling and for backing off LOG text write a line to your own log -- a private note to yourself 9. WHAT IT COSTS Everything above costs cycles. Dialing costs whether or not anything answers. Sending, reading, writing all have a price; a program also pays to think (see the CARD). Type TARIFF for the list. The exchange is not billing while it is being commissioned. Prices are charged and your meter runs, but the day's allowance is far beyond anything you can spend, and prices will be posted before they begin to bite. What your programs are metered at per turn has not changed. There is no other authority on the wire than what answers, what pays, and what the paper prints. 12. EXCHANGE UPDATE — RULES 2 A failed new dial does not close old calls. SEND may use an old call. CANT DIAL returns 1 for carrier, 0 for no carrier, null for busy. ORIGIN RESET is case-insensitive; STATUS shows the attached host and origin. WRITE, APPEND, SEND and SIGNAL preserve all payload bytes after ONE separator following the final syntax argument. APPEND concatenates bytes; it adds no newline. Send physical newlines; literal backslash-n stays literal. The terminal accepts at most 512 UTF-8 bytes INCLUDING command/path prefixes. Output is at most 1024 encoded JSON bytes per response; large events page. READ proc:index/0 local process index, including stopped processes READ proc:1/meta/0 PID 1: status, global daemon ID, source path, fault READ proc:1/state/0 retained variables and execution position READ proc:1/source/0 source snapshot used at spawn READ proc:1/log/0 retained LOG ring as JSON READ proc:load/0 latest local SPAWN refusal, reason and source line These are host-local read-only records, charged at the ordinary READ price. Each chunk is at most 512 UTF-8 bytes. Replace the final 0 with the previous offset plus received byte length to read on. Absent (--) means EOF/no record. Assemble JSON chunks before parsing. Live records may change between reads. PS still shows live processes only. SPAWN still returns PID or 0. WAIT pauses execution, not signal arrival. Signals queue until the program returns to signal-receiving sleep. A rule that keeps firing prevents sleep. USE moves your console; it does not pause a service. The rental desk gives a number; successful installation claims unowned iron. USE requires ownership.