@satilian/plugin-mf 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +522 -2
  2. package/dist/build/bootstrap.d.ts +9 -0
  3. package/dist/build/bootstrap.js +51 -0
  4. package/dist/build/build-expose.d.ts +11 -0
  5. package/dist/build/build-expose.js +142 -0
  6. package/dist/build/build-release.d.ts +12 -0
  7. package/dist/build/build-release.js +61 -0
  8. package/dist/build/build-types.d.ts +7 -0
  9. package/dist/build/build-types.js +88 -0
  10. package/dist/build/config.d.ts +14 -0
  11. package/dist/build/config.js +1 -0
  12. package/dist/build/format-stats.d.ts +8 -0
  13. package/dist/build/format-stats.js +35 -0
  14. package/dist/build/plugin.d.ts +3 -0
  15. package/dist/build/plugin.js +87 -0
  16. package/dist/build/resolver.d.ts +1 -0
  17. package/dist/build/resolver.js +13 -0
  18. package/dist/build/shared-dependencies.d.ts +2 -0
  19. package/dist/build/shared-dependencies.js +56 -0
  20. package/dist/build/sync-types.d.ts +7 -0
  21. package/dist/build/sync-types.js +202 -0
  22. package/dist/build/type-cache.d.ts +13 -0
  23. package/dist/build/type-cache.js +160 -0
  24. package/dist/build/types-cli.d.ts +2 -0
  25. package/dist/build/types-cli.js +99 -0
  26. package/dist/build/types-options.d.ts +11 -0
  27. package/dist/build/types-options.js +10 -0
  28. package/dist/client.d.ts +12 -0
  29. package/dist/client.js +6 -0
  30. package/dist/index.d.ts +8 -0
  31. package/dist/index.js +2 -0
  32. package/dist/protocol/asset-path.d.ts +1 -0
  33. package/dist/protocol/asset-path.js +10 -0
  34. package/dist/protocol/load-error.d.ts +29 -0
  35. package/dist/protocol/load-error.js +17 -0
  36. package/dist/protocol/module.d.ts +12 -0
  37. package/dist/protocol/module.js +1 -0
  38. package/dist/protocol/network-policy.d.ts +5 -0
  39. package/dist/protocol/network-policy.js +1 -0
  40. package/dist/protocol/observability.d.ts +26 -0
  41. package/dist/protocol/observability.js +1 -0
  42. package/dist/protocol/preload.d.ts +16 -0
  43. package/dist/protocol/preload.js +1 -0
  44. package/dist/protocol/registry.d.ts +17 -0
  45. package/dist/protocol/registry.js +75 -0
  46. package/dist/protocol/release-manifest.d.ts +17 -0
  47. package/dist/protocol/release-manifest.js +29 -0
  48. package/dist/protocol/remote-manifest.d.ts +13 -0
  49. package/dist/protocol/remote-manifest.js +27 -0
  50. package/dist/protocol/shared-dependencies.d.ts +19 -0
  51. package/dist/protocol/shared-dependencies.js +20 -0
  52. package/dist/protocol/ssr-releases.d.ts +4 -0
  53. package/dist/protocol/ssr-releases.js +22 -0
  54. package/dist/protocol/type-manifest.d.ts +9 -0
  55. package/dist/protocol/type-manifest.js +19 -0
  56. package/dist/protocol/types-lock.d.ts +11 -0
  57. package/dist/protocol/types-lock.js +33 -0
  58. package/dist/release-manifest.test.d.ts +1 -0
  59. package/dist/release-manifest.test.js +119 -0
  60. package/dist/runtime/client/runtime.d.ts +12 -0
  61. package/dist/runtime/client/runtime.js +115 -0
  62. package/dist/runtime/client/runtime.js.LICENSE.txt +1 -0
  63. package/dist/runtime/core/manifest-loader.d.ts +6 -0
  64. package/dist/runtime/core/manifest-loader.js +29 -0
  65. package/dist/runtime/core/preload.d.ts +8 -0
  66. package/dist/runtime/core/preload.js +45 -0
  67. package/dist/runtime/core/remote-source.d.ts +32 -0
  68. package/dist/runtime/core/remote-source.js +159 -0
  69. package/dist/runtime/react/remote.d.ts +8 -0
  70. package/dist/runtime/react/remote.js +42 -0
  71. package/dist/runtime/server/cache/config.d.ts +11 -0
  72. package/dist/runtime/server/cache/config.js +1 -0
  73. package/dist/runtime/server/cache/disk-cache.d.ts +10 -0
  74. package/dist/runtime/server/cache/disk-cache.js +172 -0
  75. package/dist/runtime/server/cache/entry.d.ts +13 -0
  76. package/dist/runtime/server/cache/entry.js +47 -0
  77. package/dist/runtime/server/cache/lock.d.ts +3 -0
  78. package/dist/runtime/server/cache/lock.js +115 -0
  79. package/dist/runtime/server/cache/paths.d.ts +2 -0
  80. package/dist/runtime/server/cache/paths.js +17 -0
  81. package/dist/runtime/server/cache/prune.d.ts +4 -0
  82. package/dist/runtime/server/cache/prune.js +88 -0
  83. package/dist/runtime/server/loader.d.ts +11 -0
  84. package/dist/runtime/server/loader.js +49 -0
  85. package/dist/runtime/server/runtime.d.ts +18 -0
  86. package/dist/runtime/server/runtime.js +106 -0
  87. package/dist/server.d.ts +13 -0
  88. package/dist/server.js +6 -0
  89. package/dist/shared.d.ts +2 -0
  90. package/dist/shared.js +1 -0
  91. package/dist/sharing/registry.d.ts +13 -0
  92. package/dist/sharing/registry.js +69 -0
  93. package/dist/transport/loading.d.ts +16 -0
  94. package/dist/transport/loading.js +186 -0
  95. package/dist/transport/network-policy.d.ts +4 -0
  96. package/dist/transport/network-policy.js +30 -0
  97. package/dist/transport/observability.d.ts +9 -0
  98. package/dist/transport/observability.js +111 -0
  99. package/dist/transport/registry.d.ts +14 -0
  100. package/dist/transport/registry.js +96 -0
  101. package/dist/transport/release-loader.d.ts +4 -0
  102. package/dist/transport/release-loader.js +12 -0
  103. package/package.json +74 -6
package/README.md CHANGED
@@ -1,3 +1,523 @@
1
- # Temporary Holding Version
1
+ # Rslib project
2
+
3
+ ## Setup
4
+
5
+ Install the dependencies for the entire workspace:
6
+
7
+ ```bash
8
+ pnpm install
9
+ ```
10
+
11
+ ## Get started
12
+
13
+ Build the library, builds all examples, then starts their servers in parallel:
14
+
15
+ - Open [http://localhost:3000](http://localhost:3000) for the shell;
16
+ - host-1, host-2 and sub-host-1 run on ports 3001, 3002 and 4001.
17
+ - Press Ctrl+C to stop the servers.
18
+ - Rerun the command after changing library code.
19
+
20
+ ```bash
21
+ pnpm start
22
+ ```
23
+
24
+ Build the library:
25
+
26
+ ```bash
27
+ pnpm run build
28
+ ```
29
+
30
+ Build the library in watch mode:
31
+
32
+ ```bash
33
+ pnpm run dev
34
+ ```
35
+
36
+ Run tests:
37
+
38
+ ```bash
39
+ pnpm run test
40
+ ```
41
+
42
+ Run tests in watch mode:
43
+
44
+ ```bash
45
+ pnpm run test:watch
46
+ ```
47
+
48
+ ## Provider releases and rollback
49
+
50
+ Provider builds preserve `dist/mf/` during Rsbuild output cleanup, including the
51
+ current pointer and previous releases. Other output files follow the configured
52
+ cleanup rules. Each successful release includes `mf/<releaseId>/pointer.json`,
53
+ a snapshot of the root `mf/manifest.json` for rollback; its paths are relative to
54
+ `mf/`, not to the snapshot directory.
55
+
56
+ Publish the complete `mf/<releaseId>/` directory before replacing
57
+ `mf/manifest.json`. On a filesystem, replace the pointer with a temporary file
58
+ and rename in the same directory; on object storage, use the storage's atomic
59
+ object replacement. Keep older release directories when deploying a new build.
60
+ Configure `Cache-Control: no-store` for the root pointer and long-lived immutable
61
+ caching for files inside release directories. Serialize deployments per provider
62
+ so an older build cannot overwrite a newer deployment's pointer.
63
+
64
+ To roll back, verify that the target release's server, client and types artifacts
65
+ are still available, then atomically replace `mf/manifest.json` with the contents
66
+ of that release's `pointer.json`. New SSR requests select the restored release;
67
+ in-flight requests and open pages keep their previously selected versions.
68
+
69
+ Releases are retained indefinitely by default; the plugin does not prune them.
70
+ A finite retention period requires a defined maximum lifetime for an open page,
71
+ including delayed imports, plus HTML/CDN cache lifetime and the rollback window.
72
+ Measure retention from the last time a release stopped being current, including
73
+ after a rollback. Never remove the current release or releases inside that window.
74
+ Incomplete unpublished release directories may be removed after their build has
75
+ stopped. Legacy providers without versioned paths cannot offer these guarantees.
76
+
77
+ ## Server module cache
78
+
79
+ Configure the cache before creating remotes or starting SSR:
80
+
81
+ ```ts
82
+ import { configureServerCache } from "plugin-mf/server";
83
+
84
+ configureServerCache({
85
+ cacheDir: "./.cache/mf",
86
+ maxBytes: 512 * 1024 * 1024,
87
+ lockTimeoutMs: 30_000,
88
+ });
89
+ ```
90
+
91
+ Defaults: `node_modules/.cache/mf` relative to the worker's working directory,
92
+ 512 MiB of completed entries, and 30 seconds waiting for the filesystem lock.
93
+ `MF_CACHE_DIR` and `MF_CACHE_MAX_BYTES` provide environment defaults. An explicit
94
+ configuration takes precedence. The directory is checked for write access on
95
+ first use. Nested remote bundles share the configured loader.
96
+
97
+ Server manifests include a `files` list for each expose, containing emitted
98
+ entries, chunks and assets. The loader downloads that set before importing the
99
+ entry, preserves relative paths and binary contents, and publishes the complete
100
+ cache directory atomically. Old manifests without `files` retain entry-only
101
+ loading. Cache identity includes provider, release ID and full asset URLs;
102
+ different providers, releases and query strings cannot share a module by filename.
103
+
104
+ `new Loader(options)` creates a standalone loader; the previous
105
+ `new Loader(cacheDir)` form is also supported. `pruneCache()` removes unused
106
+ entries until `maxBytes` is satisfied. `clearCache()` removes all unused entries.
107
+ Both return `{ bytes, protectedBytes, removedEntries, overBudgetBytes }` and leave
108
+ the in-memory module cache intact. The configured limit covers completed entries,
109
+ not transient downloads or files left by the old flat-cache implementation.
110
+
111
+ Imported releases have process-lifetime leases: deleting them could break a later
112
+ dynamic import or asset read. Cleanup skips leases belonging to live processes
113
+ and removes leases of exited processes. If live releases prevent a new release
114
+ from fitting the byte limit, loading fails explicitly; raise the limit or roll
115
+ workers. Clearing files does not unload Node's ESM module cache. Select a new
116
+ release URL for new code; restart workers to unload previously imported versions.
117
+
118
+ Cache operations use an interprocess filesystem lock, so download publication,
119
+ leases and cleanup cannot race. A dead owner's lock and abandoned download
120
+ directories are recovered on the next operation. If a process dies during lock
121
+ recovery itself, an explicit recovery error is raised: stop all cache users before
122
+ removing `.recovery`. Use a dedicated directory on a local filesystem shared by
123
+ workers on the same machine; PID leases do not coordinate different hosts.
124
+
125
+ ## Ограничение загрузки и восстановление
126
+
127
+ `pluginMF({ loading: { manifestTimeoutMs: 5000, moduleTimeoutMs: 15000,
128
+ typesTimeoutMs: 15000, retries: 2, retryDelayMs: 100,
129
+ circuitBreaker: { failureThreshold: 3, cooldownMs: 10000 } } })` задаёт политику
130
+ сборки и runtime. Все поля необязательны; в примере показаны значения по умолчанию.
131
+ Вручную созданные загрузчики настраиваются через `configureLoading` из
132
+ `plugin-mf/client` или `plugin-mf/server` до начала загрузок. Настройка общая для
133
+ одного JS realm, включая вложенные remote bundles; consumer задаёт общую политику,
134
+ providers не должны переопределять её своими значениями `loading`.
135
+
136
+ `manifestTimeoutMs` ограничивает один манифест вместе с чтением тела и повторами.
137
+ `moduleTimeoutMs` ограничивает всю загрузку expose, включая выбор релиза, манифесты,
138
+ модуль и серверные assets. `typesTimeoutMs` — весь набор типов одного provider.
139
+ Повторы используют экспоненциальную задержку в пределах исходного бюджета времени:
140
+ сетевые ошибки и HTTP 408/429/500/502/503/504, максимум `retries` дополнительных
141
+ попыток (0–10). Ошибки формата, остальные HTTP-статусы и ошибки исполнения не повторяются.
142
+ Только 404 указателя релиза включает legacy layout.
143
+
144
+ Ошибки `RemoteLoadError` содержат `remote` (URL provider), `releaseId` (если выбран),
145
+ `stage`, `code`, необязательный HTTP `status` и `cause`. Этапы: `release-manifest`,
146
+ `manifest`, `module`, `types`; коды: `LOAD_FAILED`, `HTTP_ERROR`, `TIMEOUT`,
147
+ `ABORTED`, `CIRCUIT_OPEN`. Circuit breaker учитывает неуспешные загрузки expose
148
+ или типов по provider, исключает отмену SSR, после порога отказывает без сетевых
149
+ запросов и после cooldown разрешает одну пробную загрузку. Успех закрывает circuit.
150
+
151
+ Неуспешный `React.lazy` сохраняет ошибку до явного `getRemote(name).retry(expose)`.
152
+ После этого нужно сбросить локальный Error Boundary; сгенерированные remote imports
153
+ и `createRemoteComponent` получат новый lazy при рендере. Для ручного использования
154
+ `lazyComponent` также заново получите компонент после `retry`. Повторный `retry`
155
+ не сбрасывает уже начатую попытку. Успешные модули и выбранный релиз сохраняются.
156
+ Браузерная повторная загрузка использует `mf_retry` в query того же release URL,
157
+ чтобы обойти кеш неуспешного import; CDN должен принимать этот query.
158
+
159
+ Пример `example/shell/src/remote-boundary.tsx` сочетает локальный Error Boundary,
160
+ кнопку повторной загрузки и Suspense fallback. На сервере ошибки внутри Suspense
161
+ оставляют fallback для клиентского восстановления. В `example/shell/src/server.tsx`
162
+ SSR ограничен 8 секундами и прерывается при отключении клиента:
163
+ `runWithMFRequest(callback, { signal })` отменяет ожидание remote и запросы манифестов,
164
+ а consumer также вызывает `stream.abort()`. Общая дедуплицированная серверная загрузка
165
+ имеет независимый deadline: отмена одного запроса не ломает другие SSR-запросы.
166
+ Нативный import и уже исполняемый JavaScript нельзя остановить AbortSignal;
167
+ таймаут ограничивает ожидание, но не прерывает исполнение модуля и не очищает ESM-кеш.
168
+
169
+ ## Синхронизация типов
170
+
171
+ `pluginMF({ types: { mode: "strict", concurrency: 8 } })` настраивает типы consumer.
172
+ По умолчанию используется `best-effort`: при отказе обновления сохраняется последний
173
+ успешный контракт с предупреждением и его releaseId; если кеша нет, явно сообщается
174
+ о fallback `unknown`. `strict` завершает сборку ошибкой и сохраняет предыдущие lock
175
+ и `src/mf-types.d.ts`. `off` пропускает синхронизацию без изменения файлов и сети.
176
+
177
+ В корне consumer создаётся `mf-types.lock.json`: URL provider, releaseId, URL
178
+ манифеста деклараций и SHA-256 ключ содержимого. Сохраните его в Git для CI.
179
+ Существующие записи фиксированы: обычная повторная сборка проверяет кеш и не
180
+ обращается даже к указателю provider. Новые remotes добавляются автоматически,
181
+ если не включён `frozenLockfile`. Обновление выбранных релизов требует `updateLock`.
182
+ При том же releaseId обновление проверяет только указатель, повторная загрузка
183
+ деклараций не нужна. Legacy provider фиксируется по содержимому без releaseId;
184
+ его обновление требует повторной загрузки типов.
185
+
186
+ Кеш находится в `node_modules/.cache/mf-types/<releaseId|legacy>/<cacheKey>/`.
187
+ Файлы загружаются во временный каталог; перед атомарной публикацией проверяются
188
+ пути, наличие относительных зависимостей, синтаксис TypeScript и экспорты из
189
+ манифеста. Контрольные суммы проверяются при повторном использовании. Успешные
190
+ версии сохраняются; повреждённый кеш online восстанавливается из locked URL,
191
+ а изменение содержимого locked релиза отклоняется. Проверка не заменяет `tsc`
192
+ consumer и не проверяет совместимость версий внешних пакетов.
193
+
194
+ Дополнительные `types`-параметры:
195
+
196
+ | Параметр | Поведение |
197
+ | --- | --- |
198
+ | `remotes: ["host1"]` | Синхронизировать только перечисленные remotes; остальные записи и доступные типы сохраняются |
199
+ | `concurrency: 8` | Общий лимит сетевых запросов всех remotes в одной синхронизации, включая чтение ответов и повторы |
200
+ | `frozenLockfile: true` | Требовать существующие записи всех выбранных remotes; не менять lock |
201
+ | `offline: true` | Требовать lock и использовать только проверенный локальный кеш, без сети |
202
+ | `updateLock: true` | Выбрать текущие релизы заново; несовместимо с offline/frozen |
203
+ | `lockfile: "mf-types.lock.json"` | Путь относительно корня consumer |
204
+
205
+ Для отдельной команды создайте `mf-types.config.json` рядом с `src/` consumer:
206
+
207
+ ```json
208
+ {
209
+ "remotes": { "host1": "https://host1.example/mf" },
210
+ "types": { "mode": "strict", "concurrency": 8 }
211
+ }
212
+ ```
213
+
214
+ Импортируйте `remotes` из того же JSON в конфигурацию Rsbuild. Режим `types.mode`
215
+ в Rsbuild можно установить в `off`, чтобы синхронизация выполнялась только командой.
216
+ CLI читает JSON без запуска Rsbuild; корень consumer определяется каталогом конфига.
217
+ С установленным пакетом используйте `pnpm exec plugin-mf-types`; в этом репозитории
218
+ после `pnpm build` доступны следующие команды:
219
+
220
+ ```bash
221
+ pnpm types:sync --config example/shell/mf-types.config.json --mode strict --update-lock
222
+ pnpm types:sync --config example/shell/mf-types.config.json --mode strict --frozen-lockfile
223
+ pnpm types:sync --config example/shell/mf-types.config.json --mode strict --offline --frozen-lockfile
224
+ pnpm types:sync --config example/shell/mf-types.config.json --remote host1 --update-lock
225
+ ```
226
+
227
+ `--remote` можно повторять. Флаги переопределяют соответствующие параметры JSON.
228
+ CLI использует стандартные таймауты загрузки; программный `syncTypes` экспортируется
229
+ из `plugin-mf` и поддерживает общую политику `configureLoading`. Для offline CI
230
+ восстановите `node_modules/.cache/mf-types` вместе с lock-файлом до сборки.
231
+ Без локального кеша offline/strict завершается ошибкой; online/frozen скачивает
232
+ только зафиксированные URL и проверяет содержимое. Типы фиксируются независимо от
233
+ runtime-выбора релиза: для нового контракта обновляйте lock перед сборкой consumer.
234
+ Не запускайте синхронизацию одного consumer одновременно в разных процессах:
235
+ атомарные записи защищают файлы, но не объединяют независимые обновления lock.
236
+ Локальные lock-файлы примеров игнорируются, поскольку их providers создают новые
237
+ releaseId при сборке. Генерируемый `src/mf-types.d.ts` также не хранится в Git.
238
+
239
+ ## Совместимость shared
2
240
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
241
+ `shared` и `externals` принимают строки и объекты
242
+ `{ name, version?, requiredVersion?, singleton? }`. Версия берётся из установленного
243
+ пакета consumer/provider; явная `version` проверяется на совпадение с ней.
244
+ По умолчанию `requiredVersion` — `^<installedVersion>`, `singleton` — `true`.
245
+ Диапазоны проверяются npm semver, включая правила prerelease.
246
+
247
+ `shared` регистрирует модули host с реальными версиями. `externals` описывает
248
+ зависимости provider, которые должны предоставляться host: их требования попадают
249
+ в поля `shared.client` и `shared.server` release-манифеста и проверяются до
250
+ скачивания и исполнения remote. Требования browser и SSR одинаково обязательны.
251
+ Исключение содержит provider, releaseId, имя зависимости, диапазон и доступные версии.
252
+
253
+ Запросы subpath регистрируются отдельно: namespace `react` нельзя использовать
254
+ вместо `react/jsx-runtime`. Для `react` автоматически включаются
255
+ `react/jsx-runtime` и `react/jsx-dev-runtime`; они наследуют требования корневого
256
+ пакета. Остальные subpaths перечисляются явно и используют версию своего пакета;
257
+ объект корневого пакета задаёт им значения по умолчанию.
258
+
259
+ Реестр общий для вложенных bundles одного JS realm. Singleton запрещает регистрацию
260
+ другой версии и сохраняет первую инстанцию той же версии. При `singleton: false`
261
+ можно зарегистрировать несколько версий; external получает старшую совместимую.
262
+ `getShared(name, scope?, requiredVersion?)` поддерживает тот же выбор.
263
+ `getShareScope()` возвращает снимок с наибольшей версией каждого модуля.
264
+
265
+ ### Миграция shared
266
+
267
+ Строковые массивы сохранены, но теперь используют реальные версии и проверяются.
268
+ Для другого допустимого диапазона задайте `requiredVersion` явно. Ручная
269
+ регистрация должна передавать фактическую версию:
270
+ `registerShared("react", React, "19.2.8")`. Старый default `0.0.0` сохранён
271
+ для legacy-кода и не удовлетворяет новым требованиям React.
272
+ Старые манифесты без `shared` читаются без предварительной проверки; пересоберите
273
+ providers, чтобы включить проверку. Манифесты и требования должны публиковаться
274
+ вместе с артефактами того же релиза.
275
+
276
+ ## CSP и доверенные источники
277
+
278
+ Браузерный loader использует нативный import без `new Function` и не требует
279
+ `unsafe-eval`. Rslib сохраняет magic comment для сборщика consumer. Для streaming
280
+ SSR нужны inline-скрипты React: настройте nonce в приложении либо отдельную политику
281
+ inline scripts; отсутствие `unsafe-eval` не отменяет это требование.
282
+
283
+ `pluginMF({ network: { allowedProtocols: ["https:"], allowedOrigins: ["https://provider.example"], requireServerIntegrity: true } })`
284
+ задаёт общую политику consumer. Ручная настройка доступна через `configureNetwork`
285
+ из client/server. По умолчанию разрешены HTTP(S) и только origin конкретного provider;
286
+ явный список origins заменяет это правило и должен включать все providers/CDN.
287
+ URL с credentials, другие схемы и origins отклоняются до запроса. Политика применяется
288
+ к манифестам, типам, JS, серверным assets и CSS из манифеста.
289
+
290
+ Fetch обрабатывает не более пяти redirects вручную, проверяя каждый следующий URL
291
+ и конечный адрес. Браузер скрывает Location при manual redirect: такие opaque
292
+ redirects отклоняются, поэтому browser endpoints должны быть прямыми URL.
293
+ Перед native import выполняется fetch-проверка entry с той же политикой; immutable
294
+ HTTP-кеш предотвращает повторную передачу тела. CSP `script-src`, `connect-src`
295
+ и `style-src` приложения должны разрешать необходимые sources. Imports внутри
296
+ доверенного remote-кода контролируются CSP, а не переписываются плагином.
297
+
298
+ Новые серверные манифесты содержат SHA-256 каждого entry/chunk/asset. Полный набор
299
+ проверяется при скачивании и чтении дискового кеша до первого import. Хеши входят
300
+ в идентичность кеша. Несовпадение останавливает загрузку; активный ESM-кеш не удаляется.
301
+ `requireServerIntegrity: true` отклоняет также legacy assets без хешей; по умолчанию
302
+ они принимаются для миграции. Пересоберите providers перед включением строгого режима.
303
+
304
+ Provider, манифест, deployment pipeline и локальный кеш должны быть доверенными.
305
+ Хеш в подменённом манифесте не защищает от подмены артефакта. Публикуйте неизменяемый
306
+ полный релиз через TLS до атомарного обновления pointer, ограничивайте права записи
307
+ в кеш и список sources. Серверный remote имеет права процесса host; это не sandbox.
308
+ JS уже загруженного модуля и последующие действия доверенного кода нельзя ограничить
309
+ проверкой URL в loader. Настройка network общая для realm, её задаёт consumer.
310
+
311
+ ## События, метрики и tracing
312
+
313
+ `configureObservability(handler)` из client/server подключает обработчик без
314
+ зависимости от monitoring SDK; вызов без handler отключает его. События содержат
315
+ `remote`, выбранный `releaseId`, `stage`, `operation`, тип события и длительность
316
+ в миллисекундах. `start` и `success/error` объединяются по `loadId`; также есть
317
+ `cache-hit`, `retry`, `download` и `prune`. Operation различает загрузку expose,
318
+ fetch, module import, types и disk. Объём disk-событий — проверенные скачанные bytes.
319
+ Cleanup использует системный remote `cache://server`.
320
+
321
+ `runWithMFRequest(callback, { requestId, signal })` привязывает события к SSR-запросу
322
+ через AsyncLocalStorage, общий для вложенных bundles. В примере shell `MF_TRACE=1`
323
+ включает JSON-логирование; requestId берётся из `x-request-id` либо генерируется.
324
+ Для tracing-адаптера начинайте span по start/loadId, завершайте его по success/error,
325
+ добавляйте requestId как correlation attribute. Callback может быть async; его ошибки
326
+ логируются отдельно и не нарушают загрузку. Сам adapter отвечает за экспорт spans
327
+ и ограничение своей очереди. Не сохраняйте объекты HTTP-запросов внутри handler.
328
+
329
+ `getLoadingMetrics()` возвращает снимок накопленных starts, successes, errors,
330
+ cacheHits, retries, downloadedBytes, diskHits, diskDownloads и prunedBytes.
331
+ Счётчики общие для одного JS realm; вложенные операции учитываются отдельно,
332
+ это не число HTTP-запросов пользователя. Для разрезов по provider/requestId собирайте
333
+ события своим handler. URL в событиях очищены от credentials, query и fragment;
334
+ ошибка содержит только code/status. Исходные cause и тела ответов не экспортируются.
335
+
336
+ ## Chunks, preload и бюджеты маршрута
337
+
338
+ `pluginMF({ splitChunks: true })` разрешает общие browser chunks provider.
339
+ Entry выбирается из entrypoint chunk, манифест содержит размеры всего набора JS/CSS,
340
+ а ESM entry загружает общие chunks из того же release path. По умолчанию splitChunks
341
+ выключен: больше chunks не гарантирует ускорение. Для каждого client build создаётся
342
+ `bundle-report.json` с размерами assets и модулями, присутствующими в нескольких
343
+ chunks. Размеры модулей в отчёте приблизительные, без gzip; внешние модули могут
344
+ появляться как несколько маленьких ссылок, а не реальные копии пакета.
345
+
346
+ `preloadRemotes([{ remote: "host1", expose: "Div" }], { concurrency: 4, maxRemotes: 3,
347
+ maxJSBytes: 5000000, maxCSSBytes: 200000 })` доступен из client/server.
348
+ Сначала загружаются только манифесты выбранных exposes, проверяются бюджеты, затем
349
+ выполняются импорты с ограничением числа одновременных preload-задач. Если бюджет
350
+ превышен, ни один модуль этой попытки не импортируется. maxRemotes считает разные
351
+ providers; JS/CSS учитываются один раз по полному asset URL. Манифест консервативно
352
+ описывает весь client-набор provider, включая отложенные chunks; бюджет является
353
+ верхней границей, а не прогнозом фактических bytes маршрута. Включайте в маршрут
354
+ layout и вложенные remotes. Legacy без размеров не поддерживает byte-бюджеты.
355
+
356
+ Preload прогревает модульный кеш; CSS применяется при последующем рендере компонента.
357
+ `signal` останавливает постановку новых задач, уже начатые общие загрузки сохраняются.
358
+ Ограничение относится к задачам, native import может параллельно загрузить свои chunks.
359
+ Пример shell запускает preload следующей страницы при hover/focus ссылки и сохраняет
360
+ локальный fallback при ошибке.
361
+
362
+ `pnpm benchmark:routes` измеряет Home/About через локальный Playwright и Chrome.
363
+ Если Playwright установлен отдельно, передайте `--playwright-module` с file URL
364
+ его index.mjs. `--output` выбирает JSON-файл; `--runs` — число повторов. CDP считает
365
+ encoded bytes JS/CSS, включая fetch-проверку entry перед native import; измерение
366
+ заканчивается после проверки интерактивности вложенного компонента. Fresh/reused
367
+ browser contexts разделяют холодный и повторный браузерный кеш; серверный кеш между
368
+ образцами не очищается. Это локальный smoke benchmark, не production SLA.
369
+
370
+ Результаты сравнения одной версии кода с выключенным/включённым splitChunks находятся
371
+ в `benchmarks/P2.2-before.json` и `benchmarks/P2.2-after.json` (по три прогона).
372
+ Home: холодный JS 1773182 → 1758371 bytes, запросы 16 → 19.
373
+ About: 1820954 → 1830858 bytes, запросы 15 → 19.
374
+ Медиана интерактивности cold Home 485 → 511 ms, About 535 → 475 ms;
375
+ малый объём выборки и React Refresh делают задержки шумными. Поэтому в этих примерах
376
+ разделение не включено по умолчанию; включайте его для конкретного workload после замеров.
377
+
378
+ ## Runtime registry, rollback и canary
379
+
380
+ `configureRegistry({ url: "https://config.example/mf.json", maxAgeMs: 30000 })`
381
+ и `await refreshRegistry()` доступны из client/server. JSON — объект по именам
382
+ remotes, например `{ "host1": { "url": "https://host1.example/mf", "enabled": true } }`.
383
+ Вместо URL конфигурации можно передать `remotes` прямо в configureRegistry.
384
+ Приоритет: внешний registry, локальные runtime overrides, статические aliases bundle.
385
+ Статические aliases вложенных bundles остаются локальными; runtime имена общие.
386
+ Новые имена доступны через getRemote; shorthand imports требуют alias при сборке.
387
+
388
+ Refresh валидирует формат и sources до публикации, дедуплицируется и кеширует попытку
389
+ на maxAgeMs. При отказе возвращает false, пишет предупреждение и сохраняет последний
390
+ успешный snapshot; `refreshRegistry({ force: true })` пропускает TTL. Последняя
391
+ успешная внешняя конфигурация хранится в памяти процесса; после рестарта до успешного
392
+ refresh доступны статические/локальные настройки. Изменение URL registry не позволяет
393
+ старому незавершённому запросу перезаписать конфигурацию нового источника.
394
+
395
+ Для фиксации версии entry принимает `release: { baseUrl, manifest }`, где manifest —
396
+ полная копия pointer.json нужного релиза, а baseUrl — корень mf provider (не каталог
397
+ pointer snapshot). Это сохраняет shared-требования и пути assets того же релиза.
398
+ Без release выбирается текущий pointer; `release: null` явно включает legacy layout.
399
+ `enabled: false` останавливает загрузку до обращения к provider. Aliases одного URL
400
+ не могут выбирать конфликтующие release snapshots в одном запросе.
401
+
402
+ Canary задаётся как `canary: { percentage: 10, url, release? }` рядом с основным entry.
403
+ `runWithMFRequest(callback, { selectionKey })` детерминированно выбирает вариант по
404
+ ключу пользователя/сессии и имени remote. Пустой ключ даёт один общий cohort; caller
405
+ должен передать стабильный ключ для пользовательского распределения. Пример shell
406
+ использует session cookie mf-cohort. `getRegistrySnapshot(selectionKey?)` позволяет
407
+ просмотреть выбранную конфигурацию. Canary не является криптографической рандомизацией.
408
+
409
+ Каждый SSR-запрос получает свой snapshot overrides до рендера. Обновления применяются
410
+ к новым запросам, начатые сохраняют выбор. HTML содержит mf-registry и mf-releases;
411
+ `initializeMFReleases` читает оба до hydration. Открытая страница сохраняет адреса,
412
+ cohort и релизы для отложенных imports. Для rollback опубликуйте старый release snapshot
413
+ в registry и выполните refresh; пересборка consumer не нужна. Хранение старых assets
414
+ по-прежнему обязательно. В shell переменная MF_REGISTRY_URL включает refresh перед SSR.
415
+ Для CSR без SSR вызовите refresh перед первым рендером. Network allowlist должен
416
+ разрешать registry и providers/CDN, включая сохранённые версии открытых страниц.
417
+
418
+ ## Масштаб и последовательные обновления
419
+
420
+ После `pnpm build` запустите `pnpm benchmark:scale`. Генератор
421
+ `scripts/scale-providers.mjs` поднимает 120 синтетических providers на одном
422
+ локальном HTTP-сервере с отдельными URL, одинаковыми именами файлов, immutable
423
+ релизами, статическим и отложенным server chunks и SHA-256. Артефакты и кеш сценария
424
+ создаются в node_modules/.cache, итоговый JSON по умолчанию — mf-scale-report.json
425
+ там же. `--count` задаёт не менее 100 providers, `--updates` — число последовательных
426
+ релизов (по умолчанию 20), `--output` — файл результата. Сценарий использует
427
+ React/React DOM установленных workspace-примеров и Node --expose-gc.
428
+
429
+ Сценарий завершается с ненулевым кодом при нарушении проверяемых инвариантов:
430
+ неиспользуемые providers не запрашиваются, SSR не смешивает релизы, три процесса
431
+ скачивают один набор файлов, leases защищают поздний import, ошибки ограничены
432
+ по времени и затрагивают локальный fallback. Проверяются slow/404/503, неверный JSON,
433
+ повреждённый asset и несовместимая shared-версия. После выхода workers общий кеш
434
+ очищается; после deploy/rollback новые SSR выбирают новую/восстановленную версию.
435
+
436
+ Результат текущего Windows/Node 24 прогона сохранён в `benchmarks/P2.4-scale.json`:
437
+
438
+ | Сценарий | Результат |
439
+ | --- | --- |
440
+ | 120 зарегистрировано, 1 активен, холодный старт | 43 ms, запросы только к активному provider |
441
+ | Расширение до 10 / 100 активных | 714 / 8980 ms, часть предыдущих модулей уже в кеше |
442
+ | Полностью холодные 120 активных, отдельный процесс | 14002 ms |
443
+ | 8 конкурентных тёплых SSR, по 10 активных | 99 ms суммарно |
444
+ | 3 процесса, общий кеш | 3 скачивания на 3 файла, после выхода удалён 1 entry |
445
+ | Медленный provider | Отказ за 103 ms при manifestTimeoutMs=100 |
446
+ | 20 последовательных релизов | Heap +311760 bytes после GC, RSS +12611584 bytes |
447
+ | Итоговый кеш parent-процесса | 94762 bytes, все импортированные версии защищены leases |
448
+
449
+ Guardrails измерительного сценария: cold SSR до 30 s, warm SSR до 5 s, fault до 5 s,
450
+ heap growth до 64 MiB и disk cache до 32 MiB. Это верхние пределы smoke workload,
451
+ не production SLA. Время 120 cold превышает 8-секундный deadline shell: такую страницу
452
+ нужно ограничивать route budget, прогревать или делить на независимо загружаемые области.
453
+ Общая межпроцессная блокировка сериализует публикацию холодных server releases и
454
+ заметна при большом числе активных providers. Снять её без изменения гарантий нельзя
455
+ в рамках измерительного пункта. 100 зарегистрированных remotes не означают 100 активных.
456
+
457
+ Tiny ESM fixtures не моделируют большие React bundles, CDN, разные хосты, многодневную
458
+ работу или browser heap. Счётчик bytes и память относятся к этому workload; рост
459
+ ESM-кеша на каждом новом URL ожидаем и требует worker rotation при длительной работе.
460
+ Для своего приложения повторите сценарий с реалистичными assets и заданным SLA.
461
+
462
+ ## Архитектура и проверка изменений
463
+
464
+ Пакет сохраняет четыре публичных входа: основной Rsbuild-плагин, client, server и shared.
465
+ Входные файлы служат фасадами; внутренние модули не являются публичным API.
466
+
467
+ | Модуль | Ответственность |
468
+ | --- | --- |
469
+ | protocol | Чистые контракты и проверка манифестов, путей и SSR-данных |
470
+ | transport | Общая сетевая загрузка манифеста релиза |
471
+ | build | Hooks Rsbuild, конфигурация Rspack, артефакты и типы |
472
+ | runtime/core | Выбор релиза и загрузка экспорта через ModuleLoader |
473
+ | runtime/react | Типизированные компоненты, lazy и CSS |
474
+ | runtime/client | Браузерный загрузчик и чтение SSR-релизов |
475
+ | runtime/server | Контекст SSR, ESM import и файловый кеш |
476
+ | sharing | Реестр общих зависимостей |
477
+
478
+ Сборка и runtime используют protocol и transport. Общий runtime не зависит от React
479
+ и платформенных адаптеров. Серверный Loader управляет памятью и импортом, DiskCache —
480
+ файлами; блокировки и очистка вынесены в отдельные модули. Эти границы проверяет ESLint.
481
+
482
+ Команда pnpm check запускает строгую проверку TypeScript, ESLint, существующие тесты
483
+ и сборку библиотеки. pnpm start дополнительно собирает и запускает все примеры
484
+ с ожиданием HTTP-манифестов зависимостей. Проверка SSR и гидрации выполняется отдельно.
485
+
486
+ ## Миграция типизации
487
+
488
+ Параметр `loading` и второй аргумент `runWithMFRequest` необязательны. Существующая
489
+ конфигурация работает с конечными таймаутами и ограниченными повторами по умолчанию.
490
+ Для восстановления ручного lazy после ошибки вызовите `remote.retry(expose)`,
491
+ заново получите `lazyComponent(expose)` и сбросьте Error Boundary.
492
+
493
+ Имена функций, конфигурация плагина и форматы манифестов сохранены.
494
+ getShared возвращает unknown вместо any: перед использованием значение нужно
495
+ сузить до ожидаемого контракта. Методы component и lazyComponent принимают generic
496
+ тип props; createRemoteComponent также передаёт его в lazy-компонент.
497
+
498
+ Для кеша старого плоского формата выполните online-синхронизацию один раз: она создаст
499
+ lock и версионные каталоги. Старые файлы не удаляются. Режим `best-effort` сохраняет
500
+ последние успешные типы; при их отсутствии fallback имеет тип `unknown`.
501
+ Для CI используйте `strict` и `frozenLockfile`, обновляйте lock отдельной командой
502
+ с `--update-lock`. Для полностью автономной сборки также восстановите кеш и задайте
503
+ `offline: true`. Существующий hook синхронизации сохранён; для отдельного этапа
504
+ установите `types.mode: "off"` в конфигурации Rsbuild.
505
+
506
+ ## Проектные инструменты Codex
507
+
508
+ Правила находятся в AGENTS.md, три специализированных skill — в .agents/skills.
509
+ Проектная .codex/config.toml подключает Context7 для документации и Playwright MCP
510
+ для проверки примеров в изолированном headless Chrome. Playwright закреплён на версии
511
+ 0.0.83; для запуска нужны Node.js с npx и установленный Google Chrome.
512
+ Глобальные настройки Codex не меняются. Для загрузки проектного конфига проект должен
513
+ быть доверенным; новые tools появляются после обновления MCP-подключений или новой сессии.
514
+
515
+ Context7 настроен на https://mcp.context7.com/mcp без ключа. Если для вашего доступа
516
+ потребуется авторизация или повышенный лимит, передавайте ключ через локальное окружение
517
+ и настройки заголовков клиента; не добавляйте секреты в репозиторий. Документацию сверяйте
518
+ с установленной версией и первоисточниками Rsbuild/Rspack/Rslib.
519
+
520
+ Источники настройки: [Codex](https://learn.chatgpt.com/docs/config-file/config-reference),
521
+ [skills](https://learn.chatgpt.com/docs/build-skills),
522
+ [Context7](https://github.com/upstash/context7),
523
+ [Playwright MCP](https://github.com/microsoft/playwright-mcp).
@@ -0,0 +1,9 @@
1
+ import type { Rspack } from "@rsbuild/core";
2
+ import type { PluginMFConfig } from "./config.ts";
3
+ import type { SharedRequirements } from "../protocol/shared-dependencies.ts";
4
+ type Config = {
5
+ name?: string;
6
+ entry?: Rspack.Entry;
7
+ };
8
+ export declare function modifyEntry<T extends Config>(config: T, mfConfig: PluginMFConfig, shared: SharedRequirements): void;
9
+ export {};
@@ -0,0 +1,51 @@
1
+ function modifyEntry(config, mfConfig, shared) {
2
+ if (!mfConfig.shared?.length || !config.entry) return;
3
+ const bootstrap = createSharedBootstrap(shared);
4
+ if ("string" == typeof config.entry || Array.isArray(config.entry)) {
5
+ config.entry = [
6
+ bootstrap,
7
+ ...[
8
+ config.entry
9
+ ].flat()
10
+ ];
11
+ return;
12
+ }
13
+ const entry = config.entry;
14
+ for (const [name, value] of Object.entries(entry)){
15
+ if ("string" == typeof value) {
16
+ entry[name] = [
17
+ bootstrap,
18
+ value
19
+ ];
20
+ continue;
21
+ }
22
+ if (Array.isArray(value)) {
23
+ entry[name] = [
24
+ bootstrap,
25
+ ...value
26
+ ];
27
+ continue;
28
+ }
29
+ const imports = Array.isArray(value.import) ? value.import : [
30
+ value.import
31
+ ];
32
+ value.import = [
33
+ bootstrap,
34
+ ...imports
35
+ ];
36
+ }
37
+ }
38
+ function createSharedBootstrap(requirements) {
39
+ const shared = Object.keys(requirements);
40
+ const imports = shared.map((request, index)=>`import * as shared${index} from ${JSON.stringify(request)};`).join("\n");
41
+ const registrations = shared.map((request, index)=>`registerShared(${JSON.stringify(request)}, shared${index}, ${JSON.stringify(requirements[request].version)}, "default", ${requirements[request].singleton});`).join("\n");
42
+ const source = `
43
+ ${imports}
44
+ import { getShared, registerShared } from "plugin-mf/shared";
45
+
46
+ ${registrations}
47
+ globalThis.__MF_GET_SHARED__ = getShared;
48
+ `;
49
+ return `data:text/javascript,${encodeURIComponent(source)}`;
50
+ }
51
+ export { modifyEntry };
@@ -0,0 +1,11 @@
1
+ import { type Rspack } from "@rsbuild/core";
2
+ import type { SharedRequirements } from "../protocol/shared-dependencies.ts";
3
+ export type BuildExposeProps = {
4
+ releaseId: string;
5
+ entry: Record<string, string>;
6
+ externals?: SharedRequirements;
7
+ splitChunks?: boolean;
8
+ config: Rspack.Configuration;
9
+ };
10
+ export declare function getMFOutputPath(config: Rspack.Configuration): string;
11
+ export declare function buildExpose({ entry, externals, splitChunks, releaseId, config: baseConfig }: BuildExposeProps): Promise<void>;