add phase 3 sync: remote interface, folder and s3 backends, offer, steal and combine

@@ -0,0 +1,76 @@1+//! `koh offer` — send the local saves to this machine's remote.2+3+module cli4+5+import json6+import src.machine7+import src.remote8+import src.storage9+import src.sync10+11+pub fn cmd_offer(raw []string) int {12+	args := parse('offer', raw, Options{13+		flags: ['json']14+	}) or { return usage_error(err.msg()) }15+	store := open_store() or { return refuse(args.json(), err.msg()) }16+	defer {17+		store.close()18+	}19+	mut backend := this_machine_backend() or { return refuse(args.json(), err.msg()) }20+	report := sync.offer(store, mut backend) or { return refuse(args.json(), err.msg()) }21+	if args.json() {22+		emit_json(json.encode(OfferedJson{23+			repo:    report.repo24+			saves:   report.saves25+			objects: report.objects26+			events:  report.events27+			head:    report.head28+		}))29+		return 030+	}31+	if report.saves + report.objects + report.events == 0 {32+		ok('the remote already has everything from [${report.head}]')33+		return 034+	}35+	ok('offered ${report.saves} saves · ${report.objects} objects · ${report.events} events to "${report.repo}"')36+	note('remote head is now [${report.head}]')37+	return 038+}39+40+// this_machine_backend builds the backend from the machine's saved remote.41+pub fn this_machine_backend() !remote.Backend {42+	settings := machine.load_remote()!43+	if settings.kind == machine.kind_folder {44+		return remote.new_folder(settings.path)!45+	}46+	credentials := machine.load_credentials()!47+	return remote.new_s3(settings.endpoint, settings.bucket, settings.region,48+		credentials.access_key, credentials.secret_key)!49+}50+51+// auto_offer runs after every save and checkpoint. A remote that is not set up,52+// or not reachable, must never fail the save: it prints one line and stops.53+pub fn auto_offer(store &storage.Store) {54+	if !machine.has_remote() {55+		return56+	}57+	mut backend := this_machine_backend() or {58+		note('not offered: ${err.msg()}')59+		return60+	}61+	report := sync.offer(store, mut backend) or {62+		note('not offered: ${err.msg()}')63+		return64+	}65+	if report.saves + report.objects + report.events > 0 {66+		note('offered to "${report.repo}" — ${report.saves} saves · ${report.objects} objects')67+	}68+}69+70+struct OfferedJson {71+	repo    string72+	saves   int73+	objects int74+	events  int75+	head    string76+}

@@ -0,0 +1,213 @@1+//! `koh remote` — the machine's remote, set up once and used by every repo.2+//!3+//! Setup is interactive by default, because it ends with a live connection4+//! test: a remote is only saved once it has proved it can store an object and5+//! refuse to overwrite it. `folder` and `s3` forms are available for a machine6+//! being set up by a script, and an agent can read the current setting with7+//! `--json` (which never prints the secret key).8+9+module cli10+11+import json12+import os13+import src.machine14+import src.remote15+16+pub fn cmd_remote(raw []string) int {17+	args := parse('remote', raw, Options{18+		flags: ['json', 'forget']19+	}) or { return usage_error(err.msg()) }20+	if args.flag('forget') {21+		if !machine.has_remote() {22+			return refuse(args.json(), 'this machine has no remote to forget')23+		}24+		machine.forget_remote() or { return refuse(args.json(), err.msg()) }25+		if args.json() {26+			emit_json(json.encode(RemoteJson{27+				configured: false28+			}))29+			return 030+		}31+		ok("forgot this machine's remote")32+		return 033+	}34+	if args.positional.len == 0 {35+		if !machine.has_remote() {36+			if args.json() {37+				emit_json(json.encode(RemoteJson{38+					configured: false39+				}))40+				return 041+			}42+			return setup_wizard()43+		}44+		settings := machine.load_remote() or { return refuse(args.json(), err.msg()) }45+		if args.json() {46+			emit_json(json.encode(RemoteJson{47+				configured: true48+				kind:       settings.kind49+				target:     describe(settings)50+			}))51+			return 052+		}53+		ok('remote: ${describe(settings)}')54+		note('run "koh remote folder <path>" or "koh remote s3 <endpoint> <bucket> <region>" to replace it')55+		return 056+	}57+	// A non-interactive form, still tested before it is saved.58+	return set_remote(args)59+}60+61+fn set_remote(args Args) int {62+	kind := args.positional_at(0)63+	match kind {64+		machine.kind_folder {65+			path := args.positional_at(1)66+			if path == '' {67+				return usage_error('remote folder needs a path: koh remote folder /Volumes/usb/koh')68+			}69+			settings := machine.RemoteSettings{70+				kind: machine.kind_folder71+				path: os.real_path(path)72+			}73+			return save_after_check(settings, args, '', '')74+		}75+		machine.kind_s3 {76+			endpoint := args.positional_at(1)77+			bucket := args.positional_at(2)78+			region := args.positional_at(3)79+			if endpoint == '' || bucket == '' || region == '' {80+				return usage_error('remote s3 needs an endpoint, bucket and region: koh remote s3 https://s3.fr-par.scw.cloud my-bucket fr-par')81+			}82+			access_key, secret_key := s3_keys() or { return refuse(args.json(), err.msg()) }83+			settings := machine.RemoteSettings{84+				kind:     machine.kind_s385+				endpoint: endpoint86+				bucket:   bucket87+				region:   region88+			}89+			return save_after_check(settings, args, access_key, secret_key)90+		}91+		else {92+			return usage_error('remote takes "folder" or "s3", not "${kind}"')93+		}94+	}95+}96+97+// save_after_check is the whole point: nothing is written to ~/.config/koh98+// until the remote has passed the test.99+fn save_after_check(settings machine.RemoteSettings, args Args, access_key string, secret_key string) int {100+	mut backend := build_backend(settings, access_key, secret_key) or {101+		return refuse(args.json(), err.msg())102+	}103+	remote.check(mut backend) or {104+		return refuse(args.json(), 'the remote did not pass its test: ${err.msg()}')105+	}106+	machine.save_remote(settings) or { return refuse(args.json(), err.msg()) }107+	if settings.kind == machine.kind_s3 {108+		machine.save_credentials(machine.Credentials{109+			access_key: access_key110+			secret_key: secret_key111+		}) or { return refuse(args.json(), err.msg()) }112+	}113+	if args.json() {114+		emit_json(json.encode(RemoteJson{115+			configured: true116+			kind:       settings.kind117+			target:     describe(settings)118+		}))119+		return 0120+	}121+	ok('remote set to ${describe(settings)}')122+	note('every repo on this machine now offers to it')123+	return 0124+}125+126+fn build_backend(settings machine.RemoteSettings, access_key string, secret_key string) !remote.Backend {127+	if settings.kind == machine.kind_folder {128+		return remote.new_folder(settings.path)!129+	}130+	return remote.new_s3(settings.endpoint, settings.bucket, settings.region, access_key,131+		secret_key)!132+}133+134+fn setup_wizard() int {135+	if !interactive() {136+		return fail('setting up a remote needs a terminal, or use: koh remote folder <path>, koh remote s3 <endpoint> <bucket> <region>')137+	}138+	println('  choose a remote:')139+	println('    ${amber('1')} folder   a directory, on a disk or a NAS')140+	println('    ${amber('2')} s3       an S3-compatible bucket')141+	print('  which? [1] ')142+	if os.get_line().trim_space() == '2' {143+		return wizard_s3()144+	}145+	print('  folder path: ')146+	path := os.get_line().trim_space()147+	if path == '' {148+		return fail('no path given — nothing was saved')149+	}150+	settings := machine.RemoteSettings{151+		kind: machine.kind_folder152+		path: os.real_path(path)153+	}154+	return save_after_check(settings, Args{}, '', '')155+}156+157+fn wizard_s3() int {158+	print('  endpoint [https://s3.fr-par.scw.cloud]: ')159+	endpoint := or_default(os.get_line().trim_space(), 'https://s3.fr-par.scw.cloud')160+	print('  bucket: ')161+	bucket := os.get_line().trim_space()162+	print('  region [fr-par]: ')163+	region := or_default(os.get_line().trim_space(), 'fr-par')164+	if bucket == '' {165+		return fail('no bucket given — nothing was saved')166+	}167+	access_key, secret_key := s3_keys() or { return fail(err.msg()) }168+	settings := machine.RemoteSettings{169+		kind:     machine.kind_s3170+		endpoint: endpoint171+		bucket:   bucket172+		region:   region173+	}174+	return save_after_check(settings, Args{}, access_key, secret_key)175+}176+177+// s3_keys takes the keys from the environment when a script supplies them, and178+// otherwise asks, so they never have to be typed into a shell history.179+fn s3_keys() !(string, string) {180+	access_key := os.getenv('KOH_ACCESS_KEY')181+	secret_key := os.getenv('KOH_SECRET_KEY')182+	if access_key != '' && secret_key != '' {183+		return access_key, secret_key184+	}185+	if !interactive() {186+		return error('S3 keys are missing — set KOH_ACCESS_KEY and KOH_SECRET_KEY, or run koh remote on a terminal')187+	}188+	print('  access key: ')189+	access_key_typed := os.get_line().trim_space()190+	print('  secret key: ')191+	secret_key_typed := os.get_line().trim_space()192+	if access_key_typed == '' || secret_key_typed == '' {193+		return error('both keys are needed — nothing was saved')194+	}195+	return access_key_typed, secret_key_typed196+}197+198+fn describe(settings machine.RemoteSettings) string {199+	if settings.kind == machine.kind_folder {200+		return 'folder ${settings.path}'201+	}202+	return 's3 ${settings.endpoint}/${settings.bucket} (${settings.region})'203+}204+205+fn or_default(value string, fallback string) string {206+	return if value == '' { fallback } else { value }207+}208+209+struct RemoteJson {210+	configured bool211+	kind       string212+	target     string213+}

@@ -0,0 +1,196 @@1+//! `koh steal` — bring another machine's saves in.2+//!3+//! Inside a repo this pulls the remote's new saves and combines when both4+//! machines moved. Outside one it fetches a whole repo into a new folder.5+//! `--list` shows what the remote holds.6+7+module cli8+9+import json10+import os11+import src.fmt12+import src.history13+import src.remote14+import src.snapshot15+import src.storage16+import src.sync17+18+pub fn cmd_steal(raw []string) int {19+	args := parse('steal', raw, Options{20+		flags: ['list', 'mine', 'theirs', 'json']21+	}) or { return usage_error(err.msg()) }22+	if args.flag('list') {23+		return list_repos(args)24+	}25+	if storage.find_root(os.getwd()) == none {26+		name := args.positional_at(0)27+		if name == '' {28+			return usage_error('steal needs a repo name outside a repo, e.g. koh steal myproject')29+		}30+		return clone_repo(name, args)31+	}32+	store := open_store() or { return refuse(args.json(), err.msg()) }33+	defer {34+		store.close()35+	}36+	if args.positional.len > 0 {37+		return usage_error('steal takes no name inside a repo — run it outside to fetch a whole repo')38+	}39+	mut backend := this_machine_backend() or { return refuse(args.json(), err.msg()) }40+	mut options := sync.StealOptions{41+		mine:   args.flag('mine')42+		theirs: args.flag('theirs')43+	}44+	if !options.mine && !options.theirs && interactive() && os.is_atty(1) != 0 {45+		options.ask = ask_clash46+	}47+	report := sync.steal(store, mut backend, options) or { return refuse(args.json(), err.msg()) }48+	// The remote should end up with whatever this machine just decided.49+	offered := offer_after_steal(store, mut backend)50+	if args.json() {51+		emit_json(json.encode(StolenJson{52+			repo:         report.repo53+			forward:      report.forward54+			saves:        report.fetched_saves55+			objects:      report.fetched_objects56+			events:       report.fetched_events57+			clashes:      report.clashes58+			replayed:     report.replayed59+			kept_mine:    report.kept_mine60+			head:         report.head61+			offer_failed: !offered62+		}))63+		return 064+	}65+	if report.fetched_saves == 0 {66+		ok('already up to date with "${report.repo}" — head is [${report.head}]')67+		return 068+	}69+	if report.forward {70+		ok('brought in ${report.fetched_saves} saves from "${report.repo}" — head is now [${report.head}]')71+	} else {72+		ok('brought in ${report.fetched_saves} saves from "${report.repo}"')73+		note('replayed ${report.replayed} of this machine\'s saves onto the remote head')74+		if report.kept_mine > 0 {75+			note('kept mine for ${fmt.plural(report.kept_mine, 'file')}')76+		}77+	}78+	if report.clashes.len > 0 {79+		note('${report.clashes.len} changed on both machines: ${report.clashes.join(', ')}')80+	}81+	if !offered {82+		warn('the remote was not updated — run "koh offer" when it is reachable again')83+	}84+	return 085+}86+87+// offer_after_steal pushes what this machine just decided. A failure here does88+// not undo the steal; it is reported.89+fn offer_after_steal(store &storage.Store, mut backend remote.Backend) bool {90+	if _ := sync.offer(store, mut backend) {91+		return true92+	}93+	return false94+}95+96+// ask_clash is the per-file question a terminal gets. Only a lowercase y-style97+// answer is needed here: `m` for mine, `t` for theirs.98+fn ask_clash(clash sync.Clash) sync.Side {99+	println('  ${amber('both changed')} ${clash.path}   ${clash.stat}')100+	print('    ${amber('m')}ine or ${amber('t')}heirs? [t] ')101+	answer := os.get_line().trim_space()102+	if answer == 'm' {103+		return .mine104+	}105+	return .theirs106+}107+108+fn list_repos(args Args) int {109+	mut backend := this_machine_backend() or { return refuse(args.json(), err.msg()) }110+	keys := backend.list('') or { return refuse(args.json(), err.msg()) }111+	mut names := map[string]bool{}112+	for key in keys {113+		parts := key.trim_left('/').split('/')114+		if parts.len > 0 && parts[0] != '' {115+			names[parts[0]] = true116+		}117+	}118+	mut sorted := names.keys()119+	sorted.sort()120+	if args.json() {121+		emit_json(json.encode(ReposJson{122+			repos: sorted123+		}))124+		return 0125+	}126+	if sorted.len == 0 {127+		ok('the remote has no repos yet')128+		return 0129+	}130+	for name in sorted {131+		println('  ${name}')132+	}133+	return 0134+}135+136+// clone_repo fetches a whole repo into ./<name>, for a machine that does not137+// have it yet.138+fn clone_repo(name string, args Args) int {139+	target := os.join_path(os.getwd(), name)140+	if os.exists(target) {141+		return refuse(args.json(), '${name} already exists here — run steal inside it instead')142+	}143+	mut backend := this_machine_backend() or { return refuse(args.json(), err.msg()) }144+	fetched := sync.fetch_repo(mut backend, name) or { return refuse(args.json(), err.msg()) }145+	// SQLite creates the file, not the folder holding it.146+	os.mkdir_all(target, os.MkdirParams{}) or { return refuse(args.json(), err.msg()) }147+	mut store := storage.create(target) or { return refuse(args.json(), err.msg()) }148+	defer {149+		store.close()150+	}151+	store.begin() or { return refuse(args.json(), err.msg()) }152+	sync.write_fetched(store, fetched) or {153+		store.rollback()154+		return refuse(args.json(), err.msg())155+	}156+	history.set_head(store, fetched.head) or {157+		store.rollback()158+		return refuse(args.json(), err.msg())159+	}160+	store.commit() or { return refuse(args.json(), err.msg()) }161+	files := history.files_of(store, fetched.head) or { return refuse(args.json(), err.msg()) }162+	snapshot.restore_files(store, target, snapshot.Ignore{}, files, []) or {163+		return refuse(args.json(), err.msg())164+	}165+	if args.json() {166+		emit_json(json.encode(StolenJson{167+			repo:    name168+			forward: true169+			saves:   fetched.saves.len170+			objects: fetched.repo_objects.len171+			events:  fetched.events_out.len172+			head:    fetched.head173+		}))174+		return 0175+	}176+	ok('fetched "${name}" into ${target}')177+	note('${fetched.saves.len} saves at [${fetched.head}]')178+	return 0179+}180+181+struct ReposJson {182+	repos []string183+}184+185+struct StolenJson {186+	repo         string187+	forward      bool188+	saves        int189+	objects      int190+	events       int191+	clashes      []string192+	replayed     int193+	kept_mine    int194+	head         string195+	offer_failed bool196+}

@@ -0,0 +1,111 @@1+//! Machine-wide remote settings.2+//!3+//! Everything machine-specific lives in `~/.config/koh/`, never inside a repo:4+//! one remote per machine, and the S3 keys in a file only the user can read.5+//! The format is plain `key=value` lines so it can be read and edited by hand.6+7+module machine8+9+import os10+11+pub const remote_file = 'remote'12+pub const credentials_file = 'credentials'13+14+pub const kind_folder = 'folder'15+pub const kind_s3 = 's3'16+17+pub struct RemoteSettings {18+pub:19+	kind     string20+	path     string // folder backend21+	endpoint string // s3 backend22+	bucket   string23+	region   string24+}25+26+pub struct Credentials {27+pub:28+	access_key string29+	secret_key string30+}31+32+pub fn save_remote(settings RemoteSettings) ! {33+	os.mkdir_all(config_dir(), os.MkdirParams{})!34+	mut text := '# written by koh remote — the remote for every repo on this machine\n'35+	text += 'kind=${settings.kind}\n'36+	if settings.kind == kind_folder {37+		text += 'path=${settings.path}\n'38+	} else {39+		text += 'endpoint=${settings.endpoint}\n'40+		text += 'bucket=${settings.bucket}\n'41+		text += 'region=${settings.region}\n'42+	}43+	os.write_file(config_path(remote_file), text)!44+}45+46+pub fn load_remote() !RemoteSettings {47+	text := os.read_file(config_path(remote_file)) or {48+		return error('this machine has no remote yet — run "koh remote"')49+	}50+	values := parse_config(text)51+	settings := RemoteSettings{52+		kind:     values['kind'] or { '' }53+		path:     values['path'] or { '' }54+		endpoint: values['endpoint'] or { '' }55+		bucket:   values['bucket'] or { '' }56+		region:   values['region'] or { '' }57+	}58+	if settings.kind !in [kind_folder, kind_s3] {59+		return error('the remote setting in ${config_path(remote_file)} is not readable — run "koh remote" again')60+	}61+	return settings62+}63+64+pub fn has_remote() bool {65+	return os.is_file(config_path(remote_file))66+}67+68+pub fn forget_remote() ! {69+	if os.exists(config_path(remote_file)) {70+		os.rm(config_path(remote_file))!71+	}72+}73+74+// save_credentials writes the keys so that only the user can read them.75+pub fn save_credentials(credentials Credentials) ! {76+	os.mkdir_all(config_dir(), os.MkdirParams{})!77+	mut text := '# written by koh remote — keep this file private\n'78+	text += 'access_key=${credentials.access_key}\n'79+	text += 'secret_key=${credentials.secret_key}\n'80+	path := config_path(credentials_file)81+	os.write_file(path, text)!82+	os.chmod(path, 0o600)!83+}84+85+pub fn load_credentials() !Credentials {86+	text := os.read_file(config_path(credentials_file)) or {87+		return error('this machine has no S3 keys yet — run "koh remote"')88+	}89+	values := parse_config(text)90+	credentials := Credentials{91+		access_key: values['access_key'] or { '' }92+		secret_key: values['secret_key'] or { '' }93+	}94+	if credentials.access_key == '' || credentials.secret_key == '' {95+		return error('the S3 keys in ${config_path(credentials_file)} are incomplete — run "koh remote" again')96+	}97+	return credentials98+}99+100+fn parse_config(text string) map[string]string {101+	mut values := map[string]string{}102+	for line in text.split_into_lines() {103+		trimmed := line.trim_space()104+		if trimmed == '' || trimmed.starts_with('#') {105+			continue106+		}107+		at := trimmed.index('=') or { continue }108+		values[trimmed[..at].trim_space()] = trimmed[at + 1..].trim_space()109+	}110+	return values111+}

@@ -0,0 +1,42 @@1+module machine2+3+import os4+5+fn with_temp_config(name string) string {6+	dir := os.join_path(os.temp_dir(), 'koh3_machine_${os.getpid()}_${name}')7+	os.rmdir_all(dir) or {}8+	return dir9+}10+11+// The settings file is machine-wide and lives outside every repo, so these12+// tests write into a temporary home instead.13+fn test_remote_settings_round_trip() {14+	home := with_temp_config('remote')15+	defer {16+		os.rmdir_all(home) or {}17+	}18+	// load_remote reads the real machine config, so only the parse and the19+	// shape are checked here.20+	values := parse_config('# comment\nkind=folder\npath=/tmp/remote\n\n')21+	assert values['kind'] == 'folder'22+	assert values['path'] == '/tmp/remote'23+	assert values.len == 224+}25+26+fn test_parse_config_ignores_junk_and_keeps_later_values() {27+	values := parse_config('28+# a comment29+kind=s330+endpoint = https://s3.fr-par.scw.cloud31+kind=folder32+')33+	assert values['kind'] == 'folder'34+	assert values['endpoint'] == 'https://s3.fr-par.scw.cloud'35+	assert values.len == 236+}37+38+fn test_config_paths_are_outside_the_repo() {39+	assert config_dir().ends_with('.config/koh')40+	assert config_path(remote_file).ends_with('.config/koh/remote')41+	assert config_path(credentials_file).ends_with('.config/koh/credentials')42+}

@@ -0,0 +1,159 @@1+//! The folder backend: a remote that is just a directory.2+//!3+//! Every sync test in the project runs against this backend, because it needs4+//! no network and no account. It is also a real backend in its own right — a5+//! sync folder on an external disk or a NAS is a perfectly good remote.6+//!7+//! Publish is a hard link, which fails when the name already exists: no partial8+//! file and no overwrite is ever visible to a reader.9+10+module remote11+12+import crypto.blake313+import time14+import os15+16+pub struct Folder {17+pub:18+	base string19+}20+21+// new_folder points a backend at a directory, creating it when missing.22+pub fn new_folder(base string) !Folder {23+	os.mkdir_all(base, os.MkdirParams{})!24+	return Folder{25+		base: base26+	}27+}28+29+pub fn (mut f Folder) get(key string) !Object {30+	path := f.path_of(key)31+	if !os.is_file(path) {32+		return Object{}33+	}34+	body := os.read_bytes(path)!35+	return Object{36+		found: true37+		body:  body38+		tag:   tag_of(body)39+	}40+}41+42+pub fn (mut f Folder) list(prefix string) ![]string {43+	dir := os.join_path(f.base, prefix)44+	if !os.is_dir(dir) {45+		return []string{}46+	}47+	mut keys := []string{}48+	mut walk := [prefix]49+	for walk.len > 0 {50+		relative := walk.pop()51+		for name in os.ls(f.path_of(relative))! {52+			child := if relative == '' { name } else { '${relative}/${name}' }53+			if os.is_dir(f.path_of(child)) {54+				walk << child55+			} else {56+				keys << child57+			}58+		}59+	}60+	keys.sort()61+	return keys62+}63+64+// put_if_absent writes a temp file in the target directory and hard-links it65+// into place. `link` fails when the name is taken, so a racing writer loses66+// cleanly instead of overwriting.67+pub fn (mut f Folder) put_if_absent(key string, body []u8) !bool {68+	path := f.path_of(key)69+	dir := os.dir(path)70+	os.mkdir_all(dir, os.MkdirParams{})!71+	temporary := '${path}.tmp-${os.getpid()}'72+	os.write_file_array(temporary, body)!73+	defer {74+		if os.exists(temporary) {75+			os.rm(temporary) or {}76+		}77+	}78+	os.link(temporary, path) or {79+		if os.exists(path) {80+			return false81+		}82+		return err83+	}84+	return true85+}86+87+// put_if_match compares the current content's tag to the one the caller read88+// before writing. A lock file taken with an exclusive create serialises the89+// compare-and-swap, so two machines cannot both believe they won.90+pub fn (mut f Folder) put_if_match(key string, body []u8, tag string) !bool {91+	path := f.path_of(key)92+	os.mkdir_all(os.dir(path), os.MkdirParams{})!93+	guard := '${path}.lock'94+	if !take_lock(guard)! {95+		clear_stale_lock(guard)96+		if !take_lock(guard)! {97+			return false98+		}99+	}100+	defer {101+		release_lock(guard)102+	}103+	if tag != '' {104+		current := f.get(key)!105+		if !current.found || current.tag != tag {106+			return false107+		}108+	} else if f.get(key)!.found {109+		return false110+	}111+	temporary := '${path}.tmp-${os.getpid()}'112+	os.write_file_array(temporary, body)!113+	os.mv(temporary, path, os.MvParams{})!114+	return true115+}116+117+// take_lock claims a lock path by hard-linking a fresh file into place. `link`118+// fails when the name exists, so exactly one writer can hold it.119+fn take_lock(path string) !bool {120+	fresh := '${path}.${os.getpid()}.${time.now().unix_nano()}'121+	os.write_file(fresh, '${os.getpid()}')!122+	defer {123+		os.rm(fresh) or {}124+	}125+	os.link(fresh, path) or { return false }126+	return true127+}128+129+fn release_lock(path string) {130+	os.rm(path) or {}131+}132+133+// clear_stale_lock removes a lock left behind by a writer that died mid-swap.134+// A lock a minute old is not a swap in progress; it is debris, and leaving it135+// would block this remote for ever.136+fn clear_stale_lock(path string) {137+	info := os.stat(path) or { return }138+	if time.now().unix() - info.mtime > 60 {139+		os.rm(path) or {}140+	}141+}142+143+pub fn (mut f Folder) delete(key string) ! {144+	path := f.path_of(key)145+	if os.exists(path) {146+		os.rm(path)!147+	}148+}149+150+fn (f &Folder) path_of(key string) string {151+	return os.join_path(f.base, key)152+}153+154+// tag_of is the version tag of a folder object: the hash of its bytes. A155+// reader can compute it without asking anyone, which is what the lock-free156+// compare-and-swap needs.157+pub fn tag_of(body []u8) string {158+	return blake3.sum256(body).hex()159+}

@@ -0,0 +1,91 @@1+module remote2+3+import os4+5+fn scratch(name string) !string {6+	dir := os.join_path(os.temp_dir(), 'koh3_remote_${os.getpid()}_${name}')7+	os.rmdir_all(dir) or {}8+	os.mkdir_all(dir, os.MkdirParams{})!9+	return dir10+}11+12+fn test_a_missing_key_is_not_an_error() {13+	base := scratch('missing')!14+	defer {15+		os.rmdir_all(base) or {}16+	}17+	mut backend := new_folder(base)!18+	object := backend.get('repo/nothing')!19+	assert !object.found20+	assert object.body.len == 021+}22+23+fn test_put_if_absent_refuses_a_second_write() {24+	base := scratch('absent')!25+	defer {26+		os.rmdir_all(base) or {}27+	}28+	mut backend := new_folder(base)!29+	assert backend.put_if_absent('repo/objects/abc', 'first'.bytes())!30+	assert !backend.put_if_absent('repo/objects/abc', 'second'.bytes())!31+	object := backend.get('repo/objects/abc')!32+	assert object.body == 'first'.bytes()33+	assert object.tag == tag_of('first'.bytes())34+}35+36+fn test_put_if_match_only_swaps_the_version_that_was_read() {37+	base := scratch('match')!38+	defer {39+		os.rmdir_all(base) or {}40+	}41+	mut backend := new_folder(base)!42+	backend.put_if_absent('repo/head', 'one'.bytes())!43+	tag := backend.get('repo/head')!.tag44+45+	// A stale tag loses.46+	assert !backend.put_if_match('repo/head', 'two'.bytes(), 'a-stale-tag')!47+	assert backend.get('repo/head')!.body == 'one'.bytes()48+49+	// The current tag wins.50+	assert backend.put_if_match('repo/head', 'two'.bytes(), tag)!51+	assert backend.get('repo/head')!.body == 'two'.bytes()52+53+	// An absent key can only be created when the caller read it as absent.54+	assert !backend.put_if_match('repo/fresh', 'x'.bytes(), tag)!55+	assert backend.put_if_match('repo/created', 'x'.bytes(), '')!56+	assert backend.get('repo/created')!.found57+}58+59+fn test_list_walks_the_prefix() {60+	base := scratch('list')!61+	defer {62+		os.rmdir_all(base) or {}63+	}64+	mut backend := new_folder(base)!65+	backend.put_if_absent('repo/saves/aaa', 'a'.bytes())!66+	backend.put_if_absent('repo/saves/bbb', 'b'.bytes())!67+	backend.put_if_absent('repo/objects/ccc', 'c'.bytes())!68+	assert backend.list('repo/saves')! == ['repo/saves/aaa', 'repo/saves/bbb']69+	assert backend.list('repo/nothing')!.len == 070+}71+72+fn test_delete_removes_the_key() {73+	base := scratch('delete')!74+	defer {75+		os.rmdir_all(base) or {}76+	}77+	mut backend := new_folder(base)!78+	backend.put_if_absent('repo/objects/abc', 'gone'.bytes())!79+	backend.delete('repo/objects/abc')!80+	assert !backend.get('repo/objects/abc')!.found81+}82+83+fn test_check_passes_on_a_working_remote_and_leaves_nothing_behind() {84+	base := scratch('check')!85+	defer {86+		os.rmdir_all(base) or {}87+	}88+	mut backend := new_folder(base)!89+	check(mut backend)!90+	assert !backend.get(probe_key)!.found91+}