screeps-connectivity 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.15.1
+
+### Patch Changes
+
+- 4526471: Namespace the pre-login `/api/authmod` session cache by host **and path**, not hostname alone. Behind `screeps-client-proxy` every backend is wrapped under one host (`localhost/(https://server)`), so hostname-only keys collided and one server's auth capabilities could be shown for another. Also disambiguates private servers that share a hostname on different ports. Matches the path-based namespacing already used for the persistent cache in `ScreepsClient`.
+
+## 0.15.0
+
+### Minor Changes
+
+- 66f88f8: Code panel branch management: create a new branch (clones the selected branch, with an inline name input) and set the selected branch to run on the server. The active-branch indicator now stays live via a new `set-active-branch` WebSocket subscription — `UserStore.subscribe('set-active-branch')` emits a `user:setActiveBranch` event whenever the active branch changes, including from another client or session.
+
+  The code panel can now add and delete modules: an add button in the module list opens an inline name input, and hovering a module reveals a delete button (the `main` entry module is protected). Both changes are staged locally and persisted on the next Save.
+
+  Also fixes a stale-response race in the code panel where switching branches while a previous branch's code fetch was still in flight could leave the editor showing the wrong branch's files.
+
+- 66f88f8: WebSocket compression support (opt-in): setting the new `ScreepsClientOptions.gzip` to `true` sends `gzip on` after auth, so the server deflates event frames (room updates, map stats, memory) and only transmits the compressed `gz:` form when it's actually smaller. Defaults to `false` to match the official client, which never enables it. The `gz:` decode path is always active regardless, so this is a pure opt-in bandwidth trade with no downside on small control frames.
+
 ## 0.14.0
 
 ### Minor Changes

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-2026 Bastian Hoyer
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screeps-connectivity",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "license": "ISC",
   "type": "module",
   "repository": {
@@ -24,22 +24,22 @@
       "require": "./dist/file-storage.cjs"
     }
   },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.63.0",
+    "@typescript-eslint/parser": "^8.63.0",
+    "eslint": "^10.6.0",
+    "fake-indexeddb": "^6.0.0",
+    "globals": "^17.7.0",
+    "tsup": "^8.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src tests"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^25.7.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^9.0.0",
-    "fake-indexeddb": "^6.0.0",
-    "globals": "^17.6.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.5.0",
-    "vitest": "^4.1.6"
   }
-}
+}

package/src/ScreepsClient.ts

@@ -41,6 +41,14 @@ export interface ScreepsClientOptions {
   tokenRefresh?: TokenRefreshOptions | false
   /** Override the /api/game/room-decorations response with static data (useful for dev/testing when the server doesn't support the endpoint). */
   decorationsMock?: ApiRoomDecorationsResponse
+  /**
+   * Enable WebSocket message compression by sending `gzip on` after auth. The
+   * server then deflates event frames (room updates, etc.) and only sends the
+   * compressed `gz:` form when it's smaller. Defaults to `false` — matching the
+   * official client, which never enables it. The `gz:` decode path is always
+   * active regardless, so enabling this is a pure opt-in bandwidth trade.
+   */
+  gzip?: boolean
 }
 
 export class ScreepsClient {
@@ -77,7 +85,7 @@ export class ScreepsClient {
     this.logger.log(`[screeps:client] init ${opts.url}`)
     this.cache = new Cache(namespace, opts.storage ?? null)
     this.http = new HttpClient({ url: opts.url, auth: opts.auth, logger: this.logger.child('http'), serverPassword: opts.serverPassword, decorationsMock: opts.decorationsMock })
-    this.socket = new SocketClient({ url: opts.url, WebSocket: opts.WebSocket, logger: this.logger.child('socket') })
+    this.socket = new SocketClient({ url: opts.url, WebSocket: opts.WebSocket, logger: this.logger.child('socket'), gzip: opts.gzip })
     const map2Storage = new Map2Storage({
       adapter: opts.storage ?? null,
       namespace,

package/src/http/fetchServerVersion.ts

@@ -14,7 +14,15 @@ interface CachedEntry<T> {
 
 function sessionKey(suffix: string, url: string): string {
   try {
-    return `screeps:${suffix}:${new URL(url).hostname}`
+    const parsed = new URL(url)
+    // Hostname alone isn't enough: multiple worlds can live under one host via a
+    // path (screeps.com vs screeps.com/season), and behind screeps-client-proxy
+    // every backend is wrapped under the same host (localhost/(https://server)),
+    // so the path must disambiguate them. Same path-based approach as the Cache
+    // namespace in ScreepsClient; host (incl. port) also separates private
+    // servers sharing a hostname on different ports.
+    const path = parsed.pathname.replace(/\/+$/, '')
+    return `screeps:${suffix}:${path ? `${parsed.host}${path}` : parsed.host}`
   } catch {
     return `screeps:${suffix}:${url}`
   }
@@ -60,7 +68,7 @@ export async function fetchServerVersion(url: string): Promise<ServerVersion> {
 /**
  * Fetch screepsmod-auth capabilities from `/api/authmod` without authentication.
  * Returns `null` if the server does not run screepsmod-auth.
- * The result is cached in `sessionStorage` for 5 minutes (per server hostname).
+ * The result is cached in `sessionStorage` for 5 minutes (per server host+path).
  */
 export async function fetchAuthModInfo(url: string): Promise<ApiAuthModInfoResponse | null> {
   const key = sessionKey('authmod', url)

package/src/socket/SocketClient.ts

@@ -8,6 +8,7 @@ export class SocketClient {
   private readonly wsUrl: string
   private readonly WS: WsConstructor
   private readonly logger: Logger
+  private readonly gzip: boolean
   private ws: WebSocket | null = null
   private token: string | null = null
   private authed = false
@@ -22,11 +23,14 @@ export class SocketClient {
   private readonly MAX_DELAY_MS = 60_000
   private _intentionalClose = false
 
-  constructor(opts: { url: string; WebSocket?: WsConstructor; logger?: Logger }) {
+  constructor(opts: { url: string; WebSocket?: WsConstructor; logger?: Logger; gzip?: boolean }) {
     const base = opts.url.replace(/^http/, 'ws').replace(/\/$/, '')
     this.wsUrl = `${base}/socket/websocket`
     this.WS = opts.WebSocket ?? globalThis.WebSocket
     this.logger = opts.logger ?? Logger.create()
+    // Off by default — matches the official client, which never sends `gzip on`.
+    // The decode path is always available; opt in explicitly to enable it.
+    this.gzip = opts.gzip ?? false
   }
 
   get isConnected(): boolean {
@@ -64,6 +68,11 @@ export class SocketClient {
               this.token = cmd.token
               this.emit('socket:tokenRefresh', { token: cmd.token })
             }
+            // Ask the server to deflate outbound event frames before any
+            // subscribe is flushed, so the first updates already arrive as gz:.
+            // The server only sends the compressed form when it's actually
+            // smaller, so this never enlarges small control frames.
+            if (this.gzip) this.rawSend('gzip on')
             while (this.queue.length) this.rawSend(this.queue.shift()!)
             this.emit('connected', {})
             resolve()

package/src/stores/UserStore.ts

@@ -82,7 +82,7 @@ export class UserStore extends TypedStore<UserStoreEvents> {
     return this.worldStatus()
   }
 
-  subscribe(channel: 'console' | 'cpu' | 'code'): Subscription {
+  subscribe(channel: 'console' | 'cpu' | 'code' | 'set-active-branch'): Subscription {
     this.logger.log('subscribe', channel)
     let socketSub: Subscription | null = null
     let listenerSub: Subscription | null = null
@@ -115,6 +115,8 @@ export class UserStore extends TypedStore<UserStoreEvents> {
             this.emit('user:console', { messages: msg })
           } else if (channel === 'code') {
             this.emit('user:code', data as { branch: string; modules: Record<string, string> })
+          } else if (channel === 'set-active-branch') {
+            this.emit('user:setActiveBranch', data as { activeName: 'activeWorld' | 'activeSim'; branch: string })
           }
         })
       } catch (err) {

package/src/types/events.ts

@@ -40,6 +40,7 @@ export interface UserStoreEvents {
     'user:cpu': CpuStats
     'user:console': { messages: ConsoleMessage }
     'user:code': { branch: string; modules: Record<string, string> }
+    'user:setActiveBranch': { activeName: 'activeWorld' | 'activeSim'; branch: string }
     'user:stream': Record<string, unknown>
     'user:memory': { path: string; shard: string | null; value: unknown }
     'user:mapVisual': { shard: string | null; data: string }

package/tests/http/fetchServerVersion.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { fetchAuthModInfo } from '../../src/http/fetchServerVersion.js'
+
+// Minimal in-memory sessionStorage stub (the node test env has none).
+class MemorySessionStorage {
+  private readonly map = new Map<string, string>()
+  getItem(k: string): string | null { return this.map.get(k) ?? null }
+  setItem(k: string, v: string): void { this.map.set(k, v) }
+  removeItem(k: string): void { this.map.delete(k) }
+  clear(): void { this.map.clear() }
+}
+
+describe('fetchAuthModInfo — session cache namespacing', () => {
+  beforeEach(() => {
+    vi.stubGlobal('sessionStorage', new MemorySessionStorage())
+  })
+  afterEach(() => { vi.unstubAllGlobals() })
+
+  it('does not collide between two backends wrapped under the same proxy host', async () => {
+    // Both URLs share host `localhost:8080`; only the /(backend) path differs —
+    // exactly how screeps-client-proxy addresses distinct servers. The cache key
+    // must include the path, otherwise the second lookup returns the first's data.
+    const worldUrl = 'http://localhost:8080/(https://screeps.com)'
+    const privUrl = 'http://localhost:8080/(http://my-private-server:21025)'
+    // Exact URL → payload map (no substring host matching).
+    const payloads: Record<string, string> = {
+      [`${worldUrl}/api/authmod`]: 'official',
+      [`${privUrl}/api/authmod`]: 'private',
+    }
+    const fetchMock = vi.fn().mockImplementation((input: string) => {
+      return Promise.resolve(
+        new Response(JSON.stringify({ ok: 1, backend: payloads[input] }), {
+          headers: { 'content-type': 'application/json' },
+        }),
+      )
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const world = await fetchAuthModInfo(worldUrl)
+    const priv = await fetchAuthModInfo(privUrl)
+
+    expect((world as { backend?: string })?.backend).toBe('official')
+    expect((priv as { backend?: string })?.backend).toBe('private')
+    // Both were real network fetches — neither served the other's cached entry.
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+
+    // A repeat of the first URL is served from cache (no third fetch).
+    const worldAgain = await fetchAuthModInfo(worldUrl)
+    expect((worldAgain as { backend?: string })?.backend).toBe('official')
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+})

package/tests/socket/SocketClient.test.ts

@@ -58,6 +58,31 @@ describe('SocketClient', () => {
     await expect(connectClient(client)).resolves.toBeDefined()
   })
 
+  it('does not send gzip on by default', async () => {
+    const client = makeClient()
+    const ws = await connectClient(client)
+    expect(ws.sent).not.toContain('gzip on')
+  })
+
+  it('sends gzip on when explicitly enabled, before any subscribe', async () => {
+    const client = new SocketClient({ url: 'https://screeps.com', gzip: true, WebSocket: MockWS as unknown as typeof WebSocket })
+    const connectPromise = client.connect('tok')
+    const ws = MockWS.instances[0]
+    ws.simulateOpen()
+    ws.simulateMessage('auth ok newtoken')
+    await connectPromise
+    expect(ws.sent).toContain('gzip on')
+    // gzip on must precede subscribes so the first updates already arrive as gz:
+    client.subscribe('room:shard0/W7N7')
+    expect(ws.sent.indexOf('gzip on')).toBeLessThan(ws.sent.indexOf('subscribe room:shard0/W7N7'))
+  })
+
+  it('explicit gzip:false does not send gzip on', async () => {
+    const client = new SocketClient({ url: 'https://screeps.com', gzip: false, WebSocket: MockWS as unknown as typeof WebSocket })
+    const ws = await connectClient(client)
+    expect(ws.sent).not.toContain('gzip on')
+  })
+
   it('subscribe sends subscribe message when authed', async () => {
     const client = makeClient()
     const ws = await connectClient(client)

package/tsconfig.json

@@ -11,7 +11,8 @@
     "sourceMap": true,
     "outDir": "./dist",
     "rootDir": "./src",
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
+    "ignoreDeprecations": "6.0"
   },
   "include": ["src"]
 }