@benev/archimedes 0.1.0-1

package/s/_archive/core/contact/wiring.ts

@@ -0,0 +1,212 @@
+
+import {coalesce} from "@e280/stz"
+import {StdCable} from "sparrow-rtc"
+
+import {json} from "./codecs.js"
+import {Codec} from "./types.js"
+import {u8} from "../../tools/u8.js"
+import {Contact} from "./contact.js"
+import {onChannelMessage} from "../utils/on-channel-message.js"
+
+/**
+* bob sends whatever alice sends. (alice.send->bob.send)
+*
+* bob is forwarding alice's outgoing mail.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send] --------> [send]
+*
+* [recv]           [recv]
+* ```
+*/
+export function send<O>(alice: Contact<any, O>, ...bobs: Contact<any, O>[]) {
+	return alice.send.on((output, reliable) => {
+		for (const bob of bobs)
+			bob.send(output, reliable)
+	})
+}
+
+/**
+* bob receives whatever alice receives. (alice.recv->bob.recv)
+*
+* bob is cc'd on alice's incoming mail.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send]           [send]
+*
+* [recv] --------> [recv]
+* ```
+*/
+export function recv<I>(alice: Contact<I, any>, ...bobs: Contact<I, any>[]) {
+	return alice.recv.on((input, reliable) => {
+		for (const bob of bobs)
+			bob.recv(input, reliable)
+	})
+}
+
+/**
+* bob sends and receives what alice sends and receives. (alice.send->bob.send + alice.recv->bob.recv)
+*
+* bob is alice's trusted mail confidant. he forwards her outgoing mail, and he's even cc'd on her incoming mail.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send] --------> [send]
+*
+* [recv] --------> [recv]
+* ```
+*/
+export function mirror<I, O = I>(alice: Contact<I, O>, ...bobs: Contact<I, O>[]) {
+	return coalesce(
+		send(alice, ...bobs),
+		recv(alice, ...bobs),
+	)
+}
+
+/**
+* bob sends what alice sends, alice receives what bob receives. (alice.send->bob.send + bob.recv->alice.recv)
+*
+* bob is alice's local post office. he forwards her incoming and outgoing mail.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send] --------> [send]
+*
+* [recv] <-------- [recv]
+* ```
+*/
+export function relay<I, O = I>(alice: Contact<I, O>, ...bobs: Contact<I, O>[]) {
+	return coalesce(
+		send(alice, ...bobs),
+		...bobs.map(bob => recv(bob, alice))
+	)
+}
+
+/**
+* bob receives whatever alice sends. (alice.send->bob.recv)
+*
+* bob is the recipient of alice's love letters.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send] ---\      [send]
+*            \
+* [recv]      \--> [recv]
+* ```
+*/
+export function delivery<O>(alice: Contact<any, O>, ...bobs: Contact<O, any>[]) {
+	return alice.send.on((data, reliable) => {
+		for (const bob of bobs)
+			bob.recv(data, reliable)
+	})
+}
+
+/**
+* bob sends whatever alice receives. (alice.recv->bob.send)
+*
+* bob is a federal agent illegally snooping on alice's incoming mail, and sending copies back to headquarters without a warrant.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send]      /--> [send]
+*            /
+* [recv] ---/      [recv]
+* ```
+*/
+export function spy<I>(alice: Contact<I, any>, ...bobs: Contact<any, I>[]) {
+	return alice.recv.on((data, reliable) => {
+		for (const bob of bobs)
+			bob.send(data, reliable)
+	})
+}
+
+/**
+* alice and bob both receive what the other sends.
+*
+* bob and alice are in love, and are sending each other letters.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send] ---\ /--- [send]
+*            x
+* [recv] <--/ \--> [recv]
+* ```
+*/
+export function exchange<I, O = I>(alice: Contact<I, O>, ...bobs: Contact<O, I>[]) {
+	return coalesce(
+		delivery(alice, ...bobs),
+		...bobs.map(bob => delivery(bob, alice))
+	)
+}
+
+/**
+* alice and bob both send what the other receives.
+*
+* bob and alice are having a divorce, and they are both snooping on each other's mail, and sending copies to their lawyers.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send] <--\ /--> [send]
+*            x
+* [recv] ---/ \--- [recv]
+* ```
+*/
+export function spyExchange<I, O = I>(alice: Contact<I, O>, ...bobs: Contact<O, I>[]) {
+	return coalesce(
+		spy(alice, ...bobs),
+		...bobs.map(bob => spy(bob, alice))
+	)
+}
+
+/**
+* bob becomes a relay for alice, but bob sends and receives bytes.
+*
+* ```
+* alice             bob
+* -----             ---
+* [send] --------> [send(bytes)]
+*
+* [recv] <-------- [recv(bytes)]
+* ```
+*/
+export function relayBinary(alice: Contact, bob: Contact<Uint8Array>, codec: Codec = json) {
+	return coalesce(
+		alice.send.on((output, reliable) => bob.send(codec.encode(output), reliable)),
+		bob.recv.on((input, reliable) => alice.recv(codec.decode(input), reliable)),
+	)
+}
+
+/**
+* cable becomes a relay for alice.
+*
+* ```
+* alice            cable
+* -----            -----
+* [send] --------> [send]
+*
+* [recv] <-------- [recv]
+* ```
+*/
+export function relayCable(alice: Contact, cable: StdCable, codec: Codec = json) {
+	const bob = new Contact<Uint8Array>()
+	return coalesce(
+		relayBinary(alice, bob, codec),
+		bob.send.on((output, reliable) => {
+			if (reliable) cable.reliable.send(u8(output))
+			else cable.unreliable.send(u8(output))
+		}),
+		onChannelMessage(cable.reliable, input => bob.recv(input, true)),
+		onChannelMessage(cable.unreliable, input => bob.recv(input, false)),
+	)
+}
+

package/s/_archive/core/fiber.ts

@@ -0,0 +1,94 @@
+
+import {StdCable} from "sparrow-rtc"
+import {encode, decode} from "@msgpack/msgpack"
+
+import {pub} from "../tools/pub.js"
+import {disposers} from "../tools/disposers.js"
+import {onChannelMessage} from "./utils/on-channel-message.js"
+
+/** an arbitrary data channel */
+export class Bicomm<I, O = I> {
+	send = pub<[O]>()
+	recv = pub<[I]>()
+}
+
+/** infer a fiber's input data type */
+export type FiberInput<F extends Fiber<any>> = (
+	F extends Fiber<infer M>
+		? M
+		: never
+)
+
+/** network interface */
+export class Fiber<I = any, O = I> {
+	reliable = new Bicomm<I, O>()
+	unreliable = new Bicomm<I, O>()
+
+	/** create another fiber that is the remote end connected to this one */
+	extrude() {
+		const alice = this
+		const bob = new Fiber<O, I>()
+		const detach = Fiber.entangle(alice, bob)
+		return [bob, detach] as [Fiber<O, I>, () => void]
+	}
+
+	/** this fiber becomes a proxy of the cable */
+	attachCable(cable: StdCable) {
+		this.reliable.send.on(output => cable.reliable.send(new Uint8Array(encode(output))))
+		this.unreliable.send.on(output => cable.unreliable.send(new Uint8Array(encode(output))))
+		return disposers(
+			onChannelMessage(cable.reliable, input => this.reliable.recv(decode(input) as I)),
+			onChannelMessage(cable.unreliable, input => this.unreliable.recv(decode(input) as I)),
+		)
+	}
+
+	/** create a fiber as a proxy to the given cable */
+	static fromCable<I = any, O = I>(cable: StdCable) {
+		const fiber = new Fiber<I, O>()
+		fiber.attachCable(cable)
+		return fiber
+	}
+
+	/** weld two fibers together: messages sent to one are received by the other */
+	static entangle<I, O = I>(alice: Fiber<I, O>, bob: Fiber<O, I>) {
+		return disposers(
+			alice.reliable.send.on(m => bob.reliable.recv(m)),
+			alice.unreliable.send.on(m => bob.unreliable.recv(m)),
+			bob.reliable.send.on(m => alice.reliable.recv(m)),
+			bob.unreliable.send.on(m => alice.unreliable.recv(m)),
+		)
+	}
+
+	/** create two fibers that are entangled together: messages sent to one are received by the other */
+	static makeEntangledPair<M>() {
+		const alice = new this<M>()
+		const bob = new this<M>()
+		const detangle = this.entangle<M>(alice, bob)
+		return [alice, bob, detangle] as [Fiber<M>, Fiber<M>, () => void]
+	}
+
+	/** roll multiple subfibers into a single megafiber */
+	static multiplex<C extends {[key: string]: Fiber}>(fibers: C) {
+		const megafiber = new Fiber<{[K in keyof C]: [K, FiberInput<C[K]>]}[keyof C]>()
+
+		for (const [key, subfiber] of Object.entries(fibers)) {
+			subfiber.reliable.send.on(x => megafiber.reliable.send([key, x]))
+			subfiber.unreliable.send.on(x => megafiber.unreliable.send([key, x as any]))
+		}
+
+		megafiber.reliable.recv.on(([key, data]) => {
+			const subfiber = fibers[key as any]
+			if (!subfiber) throw new Error(`unknown subfiber "${key as any}"`)
+			subfiber.reliable.recv(data as any)
+		})
+
+		megafiber.unreliable.recv.on(([key, data]) => {
+			const subfiber = fibers[key as any]
+			if (!subfiber) throw new Error(`unknown subfiber "${key as any}"`)
+			subfiber.unreliable.recv(data as any)
+		})
+
+		return megafiber
+	}
+}
+

package/s/_archive/core/liaison.ts

@@ -0,0 +1,73 @@
+
+import {Ping, Pingponger, Pong} from "@e280/renraku"
+import {AuthorId} from "./types.js"
+import {Fiber} from "./fiber.js"
+import {Bucket} from "../tools/bucket.js"
+import {Parcel} from "./parcels/types.js"
+import {ParcelInbox} from "./parcels/inbox.js"
+import {Parceller} from "./parcels/parceller.js"
+
+export type Datagram<Data> = ["data", Data]
+
+export type Mail<Data> = (
+	| Ping
+	| Pong
+	| ["data", Data]
+)
+
+export class Liaison<Data> {
+	pingponger: Pingponger
+	inbox = new ParcelInbox<Mail<Data>>()
+	parceller = new Parceller<Mail<Data>>()
+	outbox = new Bucket<Parcel<Mail<Data>>>()
+
+	constructor(
+			/** author id of the remote partner (it's their id, not ours) */
+			public authorId: AuthorId,
+
+			public fiber: Fiber<Parcel<Mail<Data>>[]>,
+		) {
+
+		this.pingponger = new Pingponger({
+			timeout: 60_000,
+			send: p => {
+				const parcel = this.parceller.wrap(p)
+				fiber.unreliable.send([parcel])
+			},
+		})
+
+		const handleIncoming = (parcels: Parcel<Mail<Data>>[]) => parcels.forEach(
+			parcel => this.inbox.give(parcel)
+		)
+
+		this.fiber.reliable.recv.on(handleIncoming)
+		this.fiber.unreliable.recv.on(handleIncoming)
+	}
+
+	queue(data: Data) {
+		const parcel = this.parceller.wrap(["data", data])
+		this.outbox.give(parcel)
+	}
+
+	send(data?: Data) {
+		const parcels = this.outbox.take()
+		if (data) parcels.push(this.parceller.wrap(["data", data]))
+		this.fiber.unreliable.send(parcels)
+	}
+
+	recv() {
+		const datas: Data[] = []
+		for (const message of this.inbox.take()) {
+			switch (message[0]) {
+				case "ping":
+				case "pong":
+					this.pingponger.recv(message)
+					break
+				default:
+					datas.push(message[1])
+			}
+		}
+		return datas
+	}
+}
+

package/s/_archive/core/parcels/inbox.ts

@@ -0,0 +1,83 @@
+
+import {Nanny} from "./utils/nanny.js"
+import {Parcel, ParcelId} from "./types.js"
+import {Averager} from "../../tools/averager.js"
+
+/** inbox delays messages with a buffer time, and actively corrects for network packet jitter */
+export class ParcelInbox<P> {
+	#start: number
+	#offsets: Averager
+	#buffer = new Map<ParcelId, Parcel<P>>
+	#nanny = new Nanny()
+
+	constructor(
+			public delay = 25,
+			public smoothing = 5,
+			private now = () => Date.now(),
+		) {
+		this.#start = now()
+		this.#offsets = new Averager(smoothing)
+	}
+
+	/** put a parcel into this inbox */
+	give(parcel: Parcel<P>) {
+		const [id, time] = parcel
+		if (this.#buffer.has(id)) return
+		this.#buffer.set(id, parcel)
+		this.#offsets.add(this.#offset(time))
+	}
+
+	/** extract all *available* parcels from this inbox */
+	take(): P[] {
+		const ready: Parcel<P>[] = []
+		const localtime = this.#localtime
+
+		for (const parcel of this.#buffer.values()) {
+			const [id, time] = parcel
+
+			// computing jitter corrective timings
+			const offset = this.#offset(time, localtime)
+			const abberation = offset - this.#offsets.average
+			const correctedTime = (time + offset) - abberation
+			const since = localtime - correctedTime
+
+			// surface parcels that are 'ready' after jitter corrections
+			if (since >= this.delay) {
+				ready.push(parcel)
+				this.#buffer.delete(id)
+
+				// also surface any parcels that have a smaller id
+				for (const parcelB of this.#buffer.values()) {
+					const [idB] = parcelB
+					if (idB < id) {
+						ready.push(parcelB)
+						this.#buffer.delete(idB)
+					}
+				}
+			}
+		}
+
+		return ready
+			.sort(sortById)
+			.filter(this.#nanny.removeDuplicates)
+			.filter(this.#nanny.removeDisorderly)
+			.map(getPayload)
+	}
+
+	get #localtime() {
+		return this.now() - this.#start
+	}
+
+	#offset(time: number, localtime = this.#localtime) {
+		return localtime - time
+	}
+}
+
+function getPayload<P>([,,payload]: Parcel<P>): P {
+	return payload
+}
+
+function sortById([idA]: Parcel<any>, [idB]: Parcel<any>) {
+	return idA - idB
+}
+

package/s/_archive/core/parcels/parceller.ts

@@ -0,0 +1,20 @@
+
+import {Parcel} from "./types.js"
+
+/** facility for wrapping messages into parcels that are ready to be handled by an inbox */
+export class Parceller<P> {
+	#id = 0
+	#start: number
+
+	constructor(private now = () => Date.now()) {
+		this.#start = now()
+	}
+
+	/** parcelize a payload (wrap it into a parcel) */
+	wrap(payload: P): Parcel<P> {
+		const id = this.#id++
+		const time = this.now() - this.#start
+		return [id, time, payload]
+	}
+}
+

package/s/_archive/core/parcels/parcels.test.ts

@@ -0,0 +1,136 @@
+
+import {Science, test, expect} from "@e280/science"
+import {ParcelInbox} from "./inbox.js"
+import {Parceller} from "./parceller.js"
+import {loop} from "../../tools/loop.js"
+
+export default Science.suite({
+
+	"one parcel": test(async() => {
+		let now = 0
+		const outbox = new Parceller<string>(() => now)
+		const inbox = new ParcelInbox<string>(100, 20, () => now)
+		const parcel = outbox.wrap("hello")
+		inbox.give(parcel)
+		now = 1000
+		const payloads = inbox.take()
+		expect(payloads.length).is(1)
+		expect(payloads.at(0)).is("hello")
+	}),
+
+	"many parcels": test(async() => {
+		let now = 0
+		const outbox = new Parceller<string>(() => now)
+		const inbox = new ParcelInbox<string>(100, 20, () => now)
+		const parcels = [...loop(100)].map(_ => {
+			now++
+			return outbox.wrap("a")
+		})
+		parcels.forEach(parcel => {
+			now++
+			inbox.give(parcel)
+		})
+		now = 1000
+		const payloads = inbox.take()
+		expect(payloads.length).is(100)
+	}),
+
+	"out of order packets are corrected": test(async() => {
+		let now = 0
+		const outbox = new Parceller<string>(() => now)
+		const inbox = new ParcelInbox<string>(100, 20, () => now)
+
+		const a = [...loop(10)].map(() => {
+			now += 1
+			return outbox.wrap("a")
+		})
+
+		const b = [...loop(10)].map(() => {
+			now += 1
+			return outbox.wrap("b")
+		})
+
+		const c = [...loop(10)].map(() => {
+			now += 1
+			return outbox.wrap("c")
+		})
+
+		// out of order
+		const parcels = [...b, ...a, ...c]
+
+		now = 100
+		parcels.forEach(parcel => {
+			now += 1
+			inbox.give(parcel)
+		})
+
+		now = 300
+		const payloads = inbox.take()
+		expect(payloads.length).is(30)
+		expect(payloads.at(5)).is("a")
+		expect(payloads.at(15)).is("b")
+		expect(payloads.at(25)).is("c")
+	}),
+
+	"literally do the buffering": test(async() => {
+		let now = 0
+		const outbox = new Parceller<string>(() => now)
+		const inbox = new ParcelInbox<string>(100, 20, () => now)
+
+		const parcels = [...loop(20)].map(() => {
+			now++
+			return outbox.wrap("a")
+		})
+
+		now = 400
+		for (const parcel of parcels) {
+			now++
+			inbox.give(parcel)
+		}
+
+		expect(inbox.take().length).is(0)
+
+		now = 510
+		expect(inbox.take().length).is(10)
+
+		now = 520
+		expect(inbox.take().length).is(10)
+
+		now = 600
+		expect(inbox.take().length).is(0)
+	}),
+
+	"specific abberation/jitter adjustment": test(async() => {
+		let now = 0
+		const outbox = new Parceller<string>(() => now)
+		const inbox = new ParcelInbox<string>(100, 20, () => now)
+
+		now = 100 // many parcels at once, establishes an average
+		const a = [...loop(20)].map(() => outbox.wrap("a"))
+
+		now = 110 // one special parcel at a different time
+		const b = outbox.wrap("b")
+
+		//////
+
+		// ingest most of the parcels at this time
+		now = 200
+		a.forEach(p => inbox.give(p))
+
+		// except our one special parcel will be particularly late
+		now = 275 // late!
+		inbox.give(b)
+
+		//////
+
+		// the first 20 should be available by now
+		now = 309
+		expect(inbox.take().length).is(20)
+
+		// the last special one should have been moved earlier,
+		// thus available by now
+		now = 320
+		expect(inbox.take().length).is(1)
+	}),
+})
+

package/s/_archive/core/parcels/types.ts

@@ -0,0 +1,5 @@
+
+export type ParcelId = number
+export type ParcelTime = number
+export type Parcel<P> = [ParcelId, ParcelTime, P]
+

package/s/_archive/core/parcels/utils/nanny.ts

@@ -0,0 +1,23 @@
+
+import {Parcel} from "../types.js"
+
+export class Nanny {
+	biggest: number = -1
+
+	removeDuplicates = ([idA]: Parcel<any>, _index: number, parcels: Parcel<any>[]) => {
+		let count = 0
+		for (const [idB] of parcels) {
+			if (idB === idA) count += 1
+			if (count > 1) return false
+		}
+		return true
+	}
+
+	removeDisorderly = ([id]: Parcel<any>) => {
+		if (id <= this.biggest)
+			return false
+		this.biggest = id
+		return true
+	}
+}
+

package/s/_archive/core/simulator.ts

@@ -0,0 +1,11 @@
+
+import {AuthorId, Schema, Telegram} from "./types.js"
+import {handleTelegram} from "./utils/handle-telegrams.js"
+
+export abstract class Simulator<xSchema extends Schema = any> {
+	static handleTelegram = handleTelegram
+	constructor(public state: xSchema["state"]) {}
+	abstract simulate(telegram: Telegram<xSchema>): xSchema["delta"]
+	abstract tailor(authorId: AuthorId, telegram: Telegram<xSchema>): Telegram<xSchema>
+}
+