mirror of
https://github.com/LorenEteval/Furious.git
synced 2026-10-10 00:08:11 +03:00
54 lines
4.6 KiB
Markdown
54 lines
4.6 KiB
Markdown
# Bundled runtime data guidance
|
|
|
|
Inherit the [nearest parent guide](../AGENTS.md). This scope owns shipped asset provenance, consumer paths and
|
|
the endpoint-map bridge. Inclusion, write access and renderer availability require separate evidence. Read
|
|
`Furious/Widget/EndpointInfoWidget.py` with `tests/test_endpoint_info.py`; paths are relative to this source
|
|
tree's root.
|
|
|
|
## Boundary and provenance
|
|
|
|
- This directory ships Xray GeoIP/geosite data, Hysteria MMDB/ACL data, the local MapLibre endpoint map, and the
|
|
bundled font. It is not a home for settings, subscriptions, or general caches. The Xray updater currently replaces
|
|
assets at the package-resolved data paths, so these files are not necessarily immutable at runtime. Review source,
|
|
installed, and packaged write permissions separately; an application refresh may appear as a source-tree change.
|
|
- Preserve upstream licenses, provenance, binary/text formats, filenames, and paths consumed by constants, backends,
|
|
tests, setuptools package data, and Nuitka. Do not incidentally reformat generated ACLs or replace binary assets.
|
|
- Markdown files in this directory are repository metadata, not runtime data. Keep top-level and nested Markdown files
|
|
excluded consistently from setuptools package data and Nuitka inclusion while preserving them in the source tree.
|
|
Native binding resources, including an engine's embedded driver, have their own package/native owner. Their inclusion
|
|
is checked through that dependency and the release artifact, not by copying them into this data directory.
|
|
- `Deploy.py --download` performs a networked refresh and may rewrite large, time-varying assets. Run it only when that
|
|
mutation is explicitly in scope; inspect integrity checks, provenance, exact changed files, and user modifications.
|
|
Validate each downloaded file and the consumer's expected format. Build downloads currently write destination
|
|
files directly; successful transfer is neither format validation nor a transaction over the asset set. Do not
|
|
apply the runtime Xray updater's staged replacement guarantee to this build path.
|
|
|
|
## Local endpoint map
|
|
|
|
- Keep vendored `maplibre-gl.js`/CSS and their license distinct from the application-owned `EndpointMap.js`/HTML
|
|
bridge. Change host behavior in the bridge and its Python consumer; a vendor replacement needs separate provenance
|
|
and compatibility review. The style requests vector tiles and glyphs from
|
|
`tiles.openfreemap.org`. This is not an offline map. Keep executable code local, preserve attribution, and review
|
|
the HTML content-security policy and the widget's attribution-link validation when changing network resources or
|
|
links. Missing tiles/network detail must degrade without crashing the renderer or the application.
|
|
- Linux Essentials-only builds deliberately operate without WebEngine; map consumers must retain their non-WebEngine
|
|
fallback. macOS/Windows packaged paths may include WebEngine and must resolve all local resources from the bundle.
|
|
Audit map assets together with `Furious/Widget/EndpointInfoWidget.py`: local loading, the WebChannel bridge, remote
|
|
tile permissions, and external attribution navigation form one boundary. Validate both the renderer payload and
|
|
host-side acceptance when that bridge changes; editing bundled JavaScript alone cannot establish host behavior.
|
|
Map-renderer readiness, tile availability, and a successful proxy egress lookup are separate observations;
|
|
missing remote map detail must not erase the validated endpoint result or trigger direct endpoint requests.
|
|
A CSP change alone does not establish that arbitrary navigation or remote executable code is allowed by the host.
|
|
Endpoint lookup and map tile/glyph loading are separate network paths. The map receives a validated presentation
|
|
payload, not a profile document or credential-bearing URI; renderer/network failure must not replace authoritative
|
|
endpoint state. Preserve the narrow WebChannel callbacks and host-side attribution allowlist with bridge changes.
|
|
|
|
## Verification
|
|
|
|
- Verify the real consuming backend/widget, source and packaged path resolution, package-data/Nuitka inclusion,
|
|
integrity and failure behavior, and license presence. Tests use fixtures or mocked downloads, never live asset
|
|
refreshes. `tests/test_endpoint_info.py` and `tests/test_public_api.py` cover map/resource consumers; release
|
|
artifacts require their own inclusion checks. Check actual artifact contents, including nested Markdown exclusions,
|
|
rather than only the presence of package-data patterns. Successful inclusion does not prove runtime write access or
|
|
optional WebEngine availability. Revalidate provenance/network claims when an asset provider or loader changes.
|