From 67495549fe55cb04c36b8ad4d3f10686b11555ae Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 01:06:21 +0000 Subject: [PATCH 1/3] Portable profile: follow the shard group's front door A server with region_group and follow_front_door takes basedir, admin_file and an enabled gaia_host's config from the group file's front door (gate behind a relay, else mainland) each time the profile loads, so moving the front door needs a bot restart and no profile edit. The profile's own values stay as the fallback. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_016WTP2TSW5ZcPxuufnDRMMP --- docs/shard-group.md | 22 ++++++++++++++++++ src/Civ13/PortableProfile.php | 42 +++++++++++++++++++++++++++++++++++ tests/windows/portable.php | 20 +++++++++++++++++ 3 files changed, 84 insertions(+) diff --git a/docs/shard-group.md b/docs/shard-group.md index 00cc8ef0..7d313ad1 100644 --- a/docs/shard-group.md +++ b/docs/shard-group.md @@ -51,6 +51,28 @@ script's detached worker; `hoststatus` shows progress. The bot runs as the same user as the group (`civ13`), so no sudo is involved. Roles are the same as for [gaia_host](gaia-host.md). +## Following the front door (`follow_front_door`) + +The host can move the group's front door (the region on the public port, the +group file's `gate` behind a routing relay, else its `mainland`) to another +region with Civ13's `shard_group.py set-gate` or the launcher's "Front door and +ports" dialog. A portable profile server that sets + +```json +"region_group": "D:/Civ13Regions/earth.json", +"follow_front_door": true +``` + +takes its region paths from the group file each time the bot starts +(`PortableProfile::followFrontDoor`): `basedir` becomes `/`, +`admin_file` the group's shared `/front-door/SQL/admins.txt` when the +group keeps one (else, where the profile names an `admin_file`, the front +door's own `SQL/admins.txt`), and an enabled `gaia_host`'s `config` that +region's `data/shard-host/host.json`. The profile is never rewritten, so after a +move only a bot restart is needed. The values written in the profile remain the +fallback when the group file cannot be read or the front door is not set up, +so keep them valid. + ## Secondary regions (`shard_of`) A region that belongs to another entry's group sets `'shard_of' => ''` diff --git a/src/Civ13/PortableProfile.php b/src/Civ13/PortableProfile.php index 6d715538..60c35f34 100644 --- a/src/Civ13/PortableProfile.php +++ b/src/Civ13/PortableProfile.php @@ -57,6 +57,11 @@ public static function load(string $file): array // A Civ13 shard group file (scripts/shard-group): every region in it is counted and listed by region. if (!is_string($server['region_group']) || !self::absoluteAdminFile($server['region_group']) || !is_file($server['region_group'])) { throw new \InvalidArgumentException('region_group must be an existing absolute shard group file path'); } } + if (array_key_exists('follow_front_door', $server)) { + // The server's paths follow whichever region is the group's front door (followFrontDoor). + if (!is_bool($server['follow_front_door']) || ($server['follow_front_door'] && !array_key_exists('region_group', $server))) { throw new \InvalidArgumentException('follow_front_door must be true or false and needs region_group'); } + if ($server['follow_front_door']) { $server = self::followFrontDoor($server); } + } foreach (['discussion','playercount','ooc','lobby','asay','ic','transit','adminlog','debug','garbage','runtime','attack'] as $field) { if (!is_string($server[$field] ?? null) || ($server[$field] !== '' && !preg_match('/^[0-9]{17,20}$/D', $server[$field]))) { throw new \InvalidArgumentException('Explicit channel string required'); } } @@ -74,6 +79,43 @@ public static function load(string $file): array return $profile; } + /** + * Point a server at the front door of its Civ13 shard group: the region players join first, which is the + * group file's `gate` behind a routing relay (`relay_port`), else its `mainland`. The host can move the + * front door to another region (Civ13 shard_group.py set-gate); with `follow_front_door` the profile needs + * no edit afterwards, only a bot restart. Sets `basedir` to /, `admin_file` to the + * group's shared /front-door/SQL/admins.txt when the group keeps one (else, where the profile names + * an admin_file, the front door's own SQL/admins.txt) and an enabled gaia_host's `config` to that region's + * host config. A group file that cannot be read, or a front door that is not set up, leaves the profile's + * own values in place, so a damaged group file never stops the bot from starting. + */ + public static function followFrontDoor(array $server): array + { + $file = $server['region_group'] ?? null; + $bytes = is_string($file) && is_file($file) ? @file_get_contents($file, false, null, 0, 1048577) : false; + $group = is_string($bytes) && strlen($bytes) <= 1048576 ? json_decode(preg_replace('/^\xEF\xBB\xBF/', '', $bytes), true, 32) : null; + if (!is_array($group) || !is_string($group['root'] ?? null) || !self::absolute($group['root']) || !is_array($group['regions'] ?? null)) { return $server; } + $ids = []; + foreach ($group['regions'] as $region) { + if (is_array($region) && is_string($region['id'] ?? null) && preg_match('/^[a-z0-9_-]{1,32}$/D', $region['id']) === 1) { $ids[] = $region['id']; } + } + if ($ids === []) { return $server; } + $relay = is_int($group['relay_port'] ?? null) && $group['relay_port'] > 0; + $front = $relay && is_string($group['gate'] ?? null) ? $group['gate'] : (is_string($group['mainland'] ?? null) ? $group['mainland'] : $ids[0]); + $root = rtrim(str_replace('\\', '/', $group['root']), '/'); + if (!in_array($front, $ids, true) || !is_dir($root.'/'.$front)) { return $server; } + $server['basedir'] = $root.'/'.$front; + if (is_file($root.'/front-door/SQL/admins.txt')) { + $server['admin_file'] = $root.'/front-door/SQL/admins.txt'; + } elseif (array_key_exists('admin_file', $server)) { + $server['admin_file'] = $server['basedir'].'/SQL/admins.txt'; + } + if (($server['gaia_host']['enabled'] ?? false) === true && is_file($server['basedir'].'/data/shard-host/host.json')) { + $server['gaia_host']['config'] = $server['basedir'].'/data/shard-host/host.json'; + } + return $server; + } + /** Replace privileged production defaults; omitted local identities stay disabled. */ public static function runtimeOptions(array $profile): array { diff --git a/tests/windows/portable.php b/tests/windows/portable.php index 1faadabe..2f539bca 100644 --- a/tests/windows/portable.php +++ b/tests/windows/portable.php @@ -45,6 +45,26 @@ function rejects(callable $call): void { try { $call(); } catch (Throwable $e) { foreach (['relative/region',[$dir.'/a'=>$dir.'/a'],[17],['relative'],array_fill(0,17,$dir),[PHP_OS_FAMILY==='Windows'?'/region':'C:/region'],null] as $shards) { $bad=$profile;$bad['servers']['test']['shards']=is_array($shards)||$shards===null?$shards:[$shards];file_put_contents($file,json_encode($bad));rejects(fn()=>PortableProfile::load($file)); } $valid=$profile;$valid['servers']['test']['region_group']=$dir.'/separate.env';file_put_contents($file,json_encode($valid));check(PortableProfile::load($file)['servers']['test']['region_group']===$dir.'/separate.env'); foreach (['relative/earth.json',$dir.'/missing.json',$dir,[$dir],null] as $group) { $bad=$profile;$bad['servers']['test']['region_group']=$group;file_put_contents($file,json_encode($bad));rejects(fn()=>PortableProfile::load($file)); } + // follow_front_door: the server's paths follow the group file's front door (gate behind a relay, else mainland). + foreach (['gaia','north'] as $region) { mkdir($dir.'/regions/'.$region.'/SQL',0777,true);mkdir($dir.'/regions/'.$region.'/data/shard-host',0777,true);file_put_contents($dir.'/regions/'.$region.'/data/shard-host/host.json','{}'); } + $groupFile=$dir.'/earth.json';$group=['root'=>$dir.'/regions','mainland'=>'gaia','gate'=>'north','relay_port'=>1717,'regions'=>[['id'=>'gaia','name'=>'Gaia','port'=>1744],['id'=>'north','name'=>'North','port'=>1714]]]; + file_put_contents($groupFile,"\xEF\xBB\xBF".json_encode($group)); + $follow=$profile;$follow['servers']['test']['region_group']=$groupFile;$follow['servers']['test']['follow_front_door']=true;$follow['servers']['test']['admin_file']=$dir.'/old-admins.txt'; + file_put_contents($file,json_encode($follow));$server=PortableProfile::load($file)['servers']['test']; + check($server['basedir']===$dir.'/regions/north');check($server['admin_file']===$dir.'/regions/north/SQL/admins.txt'); + // The host moved the front door: the same profile follows it, and uses the group's shared admins file once there is one. + $group['gate']='gaia';file_put_contents($groupFile,json_encode($group));mkdir($dir.'/regions/front-door/SQL',0777,true);file_put_contents($dir.'/regions/front-door/SQL/admins.txt',''); + $server=PortableProfile::load($file)['servers']['test']; + check($server['basedir']===$dir.'/regions/gaia');check($server['admin_file']===$dir.'/regions/front-door/SQL/admins.txt'); + $gaia=$server;$gaia['gaia_host']=['enabled'=>true,'config'=>$dir.'/old-host.json'];check(PortableProfile::followFrontDoor($gaia)['gaia_host']['config']===$dir.'/regions/gaia/data/shard-host/host.json'); + // Without a relay the mainland is the front door; an unreadable group or a missing region folder keeps the profile's own paths. + unset($group['relay_port']);$group['mainland']='north';file_put_contents($groupFile,json_encode($group));check(PortableProfile::load($file)['servers']['test']['basedir']===$dir.'/regions/north'); + $group['mainland']='moon';$group['regions'][]=['id'=>'moon'];file_put_contents($groupFile,json_encode($group));check(PortableProfile::load($file)['servers']['test']['basedir']===$dir); + file_put_contents($groupFile,'not json');$server=PortableProfile::load($file)['servers']['test'];check($server['basedir']===$dir);check($server['admin_file']===$dir.'/old-admins.txt'); + $off=$follow;$off['servers']['test']['follow_front_door']=false;file_put_contents($groupFile,json_encode($group));file_put_contents($file,json_encode($off));check(PortableProfile::load($file)['servers']['test']['basedir']===$dir); + foreach (['yes',1,null] as $value) { $bad=$follow;$bad['servers']['test']['follow_front_door']=$value;file_put_contents($file,json_encode($bad));rejects(fn()=>PortableProfile::load($file)); } + $bad=$profile;$bad['servers']['test']['follow_front_door']=true;file_put_contents($file,json_encode($bad));rejects(fn()=>PortableProfile::load($file)); + $remove=function(string $path) use (&$remove): void { foreach (array_diff(scandir($path),['.','..']) as $name) { is_dir($path.'/'.$name) ? $remove($path.'/'.$name) : unlink($path.'/'.$name); } rmdir($path); };$remove($dir.'/regions'); $bad=$profile;unset($bad['options']['role_ids']);file_put_contents($file,json_encode($bad));rejects(fn()=>PortableProfile::load($file)); $lock=PortableProcess::lock($dir);rejects(fn()=>PortableProcess::lock($dir));fclose($lock); $lock=PortableProcess::lock($dir);fclose($lock); From 394d8852b072d4db9b99a86ea11447b4ee0945d8 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 01:07:01 +0000 Subject: [PATCH 2/3] Keep the group root as the host wrote it Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_016WTP2TSW5ZcPxuufnDRMMP --- src/Civ13/PortableProfile.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Civ13/PortableProfile.php b/src/Civ13/PortableProfile.php index 60c35f34..f018e777 100644 --- a/src/Civ13/PortableProfile.php +++ b/src/Civ13/PortableProfile.php @@ -102,7 +102,7 @@ public static function followFrontDoor(array $server): array if ($ids === []) { return $server; } $relay = is_int($group['relay_port'] ?? null) && $group['relay_port'] > 0; $front = $relay && is_string($group['gate'] ?? null) ? $group['gate'] : (is_string($group['mainland'] ?? null) ? $group['mainland'] : $ids[0]); - $root = rtrim(str_replace('\\', '/', $group['root']), '/'); + $root = rtrim($group['root'], '/\\'); if (!in_array($front, $ids, true) || !is_dir($root.'/'.$front)) { return $server; } $server['basedir'] = $root.'/'.$front; if (is_file($root.'/front-door/SQL/admins.txt')) { From dae577124f728f3e77dd760bd13041510463a830 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 01:17:30 +0000 Subject: [PATCH 3/3] Follow the front door all or nothing; read group files with a byte order mark Review fixes: an enabled gaia_host whose new region has no host config keeps the whole profile as written, the group root is checked with the same path rule as admin_file, and the region roster reader accepts a group file saved with a byte order mark. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_016WTP2TSW5ZcPxuufnDRMMP --- src/Civ13/GameServer.php | 3 ++- src/Civ13/PortableProfile.php | 11 ++++++----- tests/local/heartbeat-integration.php | 2 +- tests/windows/portable.php | 4 +++- 4 files changed, 12 insertions(+), 8 deletions(-) diff --git a/src/Civ13/GameServer.php b/src/Civ13/GameServer.php index d1fb85bf..000a6ec4 100644 --- a/src/Civ13/GameServer.php +++ b/src/Civ13/GameServer.php @@ -471,7 +471,8 @@ private function loadRegionGroup(): void return; } $bytes = @is_file($this->regionGroupFile) ? @file_get_contents($this->regionGroupFile, false, null, 0, 1048577) : false; - $group = is_string($bytes) && strlen($bytes) <= 1048576 ? json_decode($bytes, true, 32) : null; + // The host's editor may save the group file with a byte order mark; Civ13 reads it either way. + $group = is_string($bytes) && strlen($bytes) <= 1048576 ? json_decode(str_starts_with($bytes, "\xEF\xBB\xBF") ? substr($bytes, 3) : $bytes, true, 32) : null; if (! is_array($group) || ! is_string($group['root'] ?? null) || $group['root'] === '' || ! is_array($group['regions'] ?? null)) { if ($this->regionGroupStamp === null) { $this->logger->warning("GameServer {$this->key}: region_group {$this->regionGroupFile} is unreadable; counting this world only."); diff --git a/src/Civ13/PortableProfile.php b/src/Civ13/PortableProfile.php index f018e777..4b1becea 100644 --- a/src/Civ13/PortableProfile.php +++ b/src/Civ13/PortableProfile.php @@ -86,7 +86,7 @@ public static function load(string $file): array * no edit afterwards, only a bot restart. Sets `basedir` to /, `admin_file` to the * group's shared /front-door/SQL/admins.txt when the group keeps one (else, where the profile names * an admin_file, the front door's own SQL/admins.txt) and an enabled gaia_host's `config` to that region's - * host config. A group file that cannot be read, or a front door that is not set up, leaves the profile's + * host config. A group file that cannot be read, or a front door that is not set up, leaves all of the profile's * own values in place, so a damaged group file never stops the bot from starting. */ public static function followFrontDoor(array $server): array @@ -94,7 +94,7 @@ public static function followFrontDoor(array $server): array $file = $server['region_group'] ?? null; $bytes = is_string($file) && is_file($file) ? @file_get_contents($file, false, null, 0, 1048577) : false; $group = is_string($bytes) && strlen($bytes) <= 1048576 ? json_decode(preg_replace('/^\xEF\xBB\xBF/', '', $bytes), true, 32) : null; - if (!is_array($group) || !is_string($group['root'] ?? null) || !self::absolute($group['root']) || !is_array($group['regions'] ?? null)) { return $server; } + if (!is_array($group) || !is_string($group['root'] ?? null) || !self::absoluteAdminFile($group['root']) || !is_array($group['regions'] ?? null)) { return $server; } $ids = []; foreach ($group['regions'] as $region) { if (is_array($region) && is_string($region['id'] ?? null) && preg_match('/^[a-z0-9_-]{1,32}$/D', $region['id']) === 1) { $ids[] = $region['id']; } @@ -104,15 +104,16 @@ public static function followFrontDoor(array $server): array $front = $relay && is_string($group['gate'] ?? null) ? $group['gate'] : (is_string($group['mainland'] ?? null) ? $group['mainland'] : $ids[0]); $root = rtrim($group['root'], '/\\'); if (!in_array($front, $ids, true) || !is_dir($root.'/'.$front)) { return $server; } + // All of it or none: host control and the region paths must never name two different regions. + $gaia = ($server['gaia_host']['enabled'] ?? false) === true; + if ($gaia && !is_file($root.'/'.$front.'/data/shard-host/host.json')) { return $server; } $server['basedir'] = $root.'/'.$front; if (is_file($root.'/front-door/SQL/admins.txt')) { $server['admin_file'] = $root.'/front-door/SQL/admins.txt'; } elseif (array_key_exists('admin_file', $server)) { $server['admin_file'] = $server['basedir'].'/SQL/admins.txt'; } - if (($server['gaia_host']['enabled'] ?? false) === true && is_file($server['basedir'].'/data/shard-host/host.json')) { - $server['gaia_host']['config'] = $server['basedir'].'/data/shard-host/host.json'; - } + if ($gaia) { $server['gaia_host']['config'] = $server['basedir'].'/data/shard-host/host.json'; } return $server; } diff --git a/tests/local/heartbeat-integration.php b/tests/local/heartbeat-integration.php index d1a71eed..166db69e 100644 --- a/tests/local/heartbeat-integration.php +++ b/tests/local/heartbeat-integration.php @@ -277,7 +277,7 @@ public function save($channel): React\Promise\PromiseInterface { $this->saves++; mkdir($sibling, 0700); $groupFile = $root.'/group.json'; $group = ['root' => dirname($root), 'regions' => [['id' => basename($root), 'name' => 'North America'], ['id' => basename($sibling), 'name' => 'Gaia'], ['id' => '../escape', 'name' => 'Bad']]]; - file_put_contents($groupFile, json_encode($group)); + file_put_contents($groupFile, "\xEF\xBB\xBF".json_encode($group)); // with a byte order mark, as a Windows editor saves it $groupProperty->setValue($server, $groupFile); try { file_put_contents($sibling.'/serverdata.txt', record('20', 'alice&bob')); diff --git a/tests/windows/portable.php b/tests/windows/portable.php index 2f539bca..c1b3a131 100644 --- a/tests/windows/portable.php +++ b/tests/windows/portable.php @@ -57,11 +57,13 @@ function rejects(callable $call): void { try { $call(); } catch (Throwable $e) { $server=PortableProfile::load($file)['servers']['test']; check($server['basedir']===$dir.'/regions/gaia');check($server['admin_file']===$dir.'/regions/front-door/SQL/admins.txt'); $gaia=$server;$gaia['gaia_host']=['enabled'=>true,'config'=>$dir.'/old-host.json'];check(PortableProfile::followFrontDoor($gaia)['gaia_host']['config']===$dir.'/regions/gaia/data/shard-host/host.json'); + unlink($dir.'/regions/north/data/shard-host/host.json');$group['gate']='north';file_put_contents($groupFile,json_encode($group));$kept=PortableProfile::followFrontDoor($gaia); + check($kept['basedir']===$dir.'/regions/gaia');check($kept['gaia_host']['config']===$dir.'/old-host.json'); // host control cannot follow: nothing moves // Without a relay the mainland is the front door; an unreadable group or a missing region folder keeps the profile's own paths. unset($group['relay_port']);$group['mainland']='north';file_put_contents($groupFile,json_encode($group));check(PortableProfile::load($file)['servers']['test']['basedir']===$dir.'/regions/north'); $group['mainland']='moon';$group['regions'][]=['id'=>'moon'];file_put_contents($groupFile,json_encode($group));check(PortableProfile::load($file)['servers']['test']['basedir']===$dir); file_put_contents($groupFile,'not json');$server=PortableProfile::load($file)['servers']['test'];check($server['basedir']===$dir);check($server['admin_file']===$dir.'/old-admins.txt'); - $off=$follow;$off['servers']['test']['follow_front_door']=false;file_put_contents($groupFile,json_encode($group));file_put_contents($file,json_encode($off));check(PortableProfile::load($file)['servers']['test']['basedir']===$dir); + $group['mainland']='north';$off=$follow;$off['servers']['test']['follow_front_door']=false;file_put_contents($groupFile,json_encode($group));file_put_contents($file,json_encode($off));check(PortableProfile::load($file)['servers']['test']['basedir']===$dir); foreach (['yes',1,null] as $value) { $bad=$follow;$bad['servers']['test']['follow_front_door']=$value;file_put_contents($file,json_encode($bad));rejects(fn()=>PortableProfile::load($file)); } $bad=$profile;$bad['servers']['test']['follow_front_door']=true;file_put_contents($file,json_encode($bad));rejects(fn()=>PortableProfile::load($file)); $remove=function(string $path) use (&$remove): void { foreach (array_diff(scandir($path),['.','..']) as $name) { is_dir($path.'/'.$name) ? $remove($path.'/'.$name) : unlink($path.'/'.$name); } rmdir($path); };$remove($dir.'/regions');