mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-02-27 18:22:41 -08:00
48 lines
2.0 KiB
Markdown
48 lines
2.0 KiB
Markdown
# IPC + Runtime Contracts
|
|
|
|
## Core Surfaces
|
|
|
|
- `src/shared/ipc/contracts.ts`: canonical channel names and payload contracts
|
|
- `src/shared/ipc/validators.ts`: runtime payload validation/parsing
|
|
- `src/preload.ts`: renderer bridge to approved IPC endpoints
|
|
- `src/main/ipc-runtime.ts`: main-process registration and handler routing
|
|
- `src/core/services/ipc.ts`: service-level invoke handling and guardrails
|
|
- `src/core/services/anki-jimaku-ipc.ts`: integration-specific IPC boundary
|
|
- `src/main/cli-runtime.ts`: CLI/runtime command boundary
|
|
|
|
## Contract Rules
|
|
|
|
- Use shared contract constants; avoid ad-hoc literal channel strings.
|
|
- Validate `invoke` payloads before domain/service logic.
|
|
- Return structured failures (`{ ok: false, error }`) where possible.
|
|
- Keep payloads narrow and explicit.
|
|
- Update contracts, validators, preload types, and handlers in the same change when shape changes.
|
|
|
|
## Add a New IPC Action
|
|
|
|
1. Add channel in `src/shared/ipc/contracts.ts`.
|
|
2. Add or extend validator in `src/shared/ipc/validators.ts`.
|
|
3. Expose typed bridge method in `src/preload.ts`.
|
|
4. Register handler in `src/main/ipc-runtime.ts` (or relevant domain runtime module).
|
|
5. Add tests for valid and malformed payload cases in `src/core/services/*`.
|
|
6. Update renderer tests when behavior or state transitions change.
|
|
|
|
## Runtime State Notes
|
|
|
|
- Prefer runtime/domain composition via `src/main/runtime/composers/*` and `src/main/runtime/domains/*`.
|
|
- Route shared mutable state updates through transition helpers in `src/main/state.ts` for migrated domains.
|
|
- Keep IPC handlers thin; avoid embedding business logic in transport wiring.
|
|
|
|
## Troubleshooting
|
|
|
|
- Unknown payload in handler: confirm validator is applied before handler/service call.
|
|
- Renderer invoke fails: verify preload bridge method and channel registration.
|
|
- Contract drift: compare shared contract, validator, preload bridge, and main handler signatures together.
|
|
|
|
## Related Docs
|
|
|
|
- [Architecture](/architecture)
|
|
- [Development](/development)
|
|
- [Configuration](/configuration)
|
|
- [Troubleshooting](/troubleshooting)
|