AI generated READMEs
This commit is contained in:
80
README.md
Normal file
80
README.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Kordophone Monorepo
|
||||
|
||||
Kordophone is an iMessage bridge: a lightweight server runs on a Mac and exposes an HTTP API so non‑Apple devices can send/receive iMessages. A set of clients (Android, Linux GTK, macOS Cocoa) talk to that API. A shared Rust library powers most clients, and a mock server helps local testing.
|
||||
|
||||
> Important: Interfacing with iMessage on macOS involves private APIs and restricted entitlements. See `server/README.md` for details and safety notes.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
Top‑level projects in this monorepo:
|
||||
|
||||
- `server/` — macOS daemon that bridges to iMessage and exposes an HTTP REST API. Written in Objective‑C/Cocoa. See `server/README.md`.
|
||||
- `core/` — Rust workspace with the shared Kordophone client library and related tooling. Used by `gtk/` and `osx/`.
|
||||
- `gtk/` — GTK4/Libadwaita Linux desktop client built on the Rust `core` library.
|
||||
- `osx/` — macOS Cocoa client that uses the Rust `core` library and talks to the local Kordophone client daemon via XPC.
|
||||
- `android/` — Android client. Currently implements its own API client (does not use the Rust library yet).
|
||||
- `mock/` — Go‑based mock server that emulates a Mac running the Kordophone server, for local development and tests.
|
||||
|
||||
Quick links:
|
||||
|
||||
- Server (mac daemon): `server/`
|
||||
- Core (Rust workspace): `core/`
|
||||
- GTK client (Linux): `gtk/`
|
||||
- macOS client (Cocoa): `osx/`
|
||||
- Android client: `android/`
|
||||
- Mock server (Go): `mock/`
|
||||
|
||||
## How It Works
|
||||
|
||||
1. The macOS Kordophone Server (`server/`) runs on a Mac with iMessage and exposes an HTTP/JSON API and a WebSocket/updates channel.
|
||||
2. Clients connect to that server to list conversations, fetch/send messages, upload/download attachments, and receive live updates.
|
||||
3. A Rust library in `core/kordophone` implements the wire protocol and client behaviors. Linux/macOS clients use this library directly; Android currently ships a native Kotlin client.
|
||||
4. The Rust client daemon (`core/kordophoned`) provides local caching and IPC (D‑Bus on Linux, XPC on macOS) for GUI apps.
|
||||
5. The `mock/` server simulates the server API for local development without a Mac.
|
||||
|
||||
## Getting Started
|
||||
|
||||
You can try the clients quickly against the mock server.
|
||||
|
||||
1) Run the mock server (no auth):
|
||||
|
||||
```bash
|
||||
cd mock
|
||||
go run ./... # or: make; ./kordophone-mock
|
||||
```
|
||||
|
||||
The mock server listens on `http://localhost:5738` and serves endpoints like `/conversations`, `/messages`, `/sendMessage`, `/attachment`, `/updates`.
|
||||
|
||||
2) Point a client at the mock server:
|
||||
|
||||
- Android: open Settings in the app and set the server host to `http://10.0.2.2:5738` (Android emulator) or `http://<your-host-ip>:5738` if running on device. Disable auth unless you started the mock with `--auth`.
|
||||
- GTK (Linux): build and run the GTK app from `gtk/` (see its README) and configure it to use the local daemon backed by the server URL.
|
||||
- macOS (Cocoa): build the app in `osx/` (see `osx/README.md`).
|
||||
|
||||
To use a real Mac server instead, set your client’s server URL to the host running `server/` with the correct scheme/port and authentication.
|
||||
|
||||
## Building
|
||||
|
||||
Below are brief notes. Each subproject’s README has more detail.
|
||||
|
||||
- Server (macOS): open `server/MessagesBridge.xcodeproj` in Xcode. See `server/README.md` for entitlements, SSL, and running.
|
||||
- Core (Rust): install Rust (stable) and run `cargo build` inside `core/`. See `core/README.md`.
|
||||
- GTK (Linux): see `gtk/README.md` for RPM build via `rpmbuild -ba dist/rpm/kordophone.spec`.
|
||||
- macOS (Cocoa): open `osx/kordophone2.xcodeproj` in Xcode. See `osx/README.md`.
|
||||
- Android: open `android/` in Android Studio and build. See `android/README.md` for configuration.
|
||||
- Mock server (Go): `cd mock && go run ./...` or `make`.
|
||||
|
||||
## Security and Entitlements
|
||||
|
||||
The macOS server uses private APIs and restricted entitlements. On production macOS builds, processes with restricted entitlements can be killed by the kernel; development requires workarounds (e.g., swizzling, hooking `imagent`) and careful code signing. See `server/README.md` for instructions and caveats.
|
||||
|
||||
## Status
|
||||
|
||||
- Android client: ships its own API client (not yet using Rust `core`).
|
||||
- GTK + macOS clients: use the Rust `core` library and integrate with the `kordophoned` client daemon for caching/IPC.
|
||||
- Mock server: useful for development; implements common endpoints and WebSocket updates.
|
||||
|
||||
## Contributing
|
||||
|
||||
Issues and PRs are welcome. If you add a new client or endpoint, please update relevant READMEs and link it from this root README. Prefer small, focused changes and keep style consistent with the existing code.
|
||||
|
||||
47
android/README.md
Normal file
47
android/README.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Kordophone Android Client
|
||||
|
||||
Android client for the Kordophone iMessage bridge. This app connects to a running Kordophone server over HTTP/JSON and streams updates.
|
||||
|
||||
Note: This client currently implements its own API layer in Kotlin and does not yet use the shared Rust `core` library.
|
||||
|
||||
## Build & Run
|
||||
|
||||
Requirements:
|
||||
|
||||
- Android Studio (AGP 8.x)
|
||||
- JDK 8+ toolchain (project uses Java 8 bytecode)
|
||||
|
||||
Steps:
|
||||
|
||||
1. Open `android/` in Android Studio.
|
||||
2. Sync Gradle and build the project.
|
||||
3. Run the `app` configuration on an emulator or device.
|
||||
|
||||
The app targets `minSdk 30`, `targetSdk 33` and uses Jetpack Compose.
|
||||
|
||||
## Configure Server
|
||||
|
||||
Set the server host and optional Basic Auth from the app’s Settings screen.
|
||||
|
||||
- Server URL for local mock (emulator): `http://10.0.2.2:5738`
|
||||
- Server URL for local mock (device): `http://<your-host-ip>:5738`
|
||||
- Credentials: match the server if auth is enabled (mock supports `--auth`).
|
||||
|
||||
Settings are persisted using `EncryptedSharedPreferences`.
|
||||
|
||||
## Modules
|
||||
|
||||
- `app/` — UI (Compose), DI (Hilt), app wiring
|
||||
- `backend/` — Kotlin API client, DB/cache (Realm), models, tests
|
||||
|
||||
## Testing with the Mock Server
|
||||
|
||||
Start the mock server in the repo root:
|
||||
|
||||
```bash
|
||||
cd mock
|
||||
go run ./... # or: make; ./kordophone-mock
|
||||
```
|
||||
|
||||
Set the app’s server URL to the mock address and run. The mock exposes `/conversations`, `/messages`, `/sendMessage`, `/attachment`, `/updates` and more.
|
||||
|
||||
68
core/README.md
Normal file
68
core/README.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Kordophone Core (Rust Workspace)
|
||||
|
||||
This directory contains the shared Rust code and tools used by Kordophone clients.
|
||||
|
||||
Workspace members:
|
||||
|
||||
- `kordophone/` — Rust client library for the Kordophone HTTP/WebSocket API. Cross‑platform.
|
||||
- `kordophone-db/` — Lightweight cache/database and models built with Diesel (SQLite).
|
||||
- `kordophoned/` — Client daemon providing local caching and IPC
|
||||
- Linux: D‑Bus
|
||||
- macOS: XPC (see notes below)
|
||||
- `kpcli/` — Command‑line interface for interacting with the API, DB, and daemon.
|
||||
- `utilities/` — Small helper tools (e.g., testing utilities).
|
||||
|
||||
## Build
|
||||
|
||||
```bash
|
||||
cd core
|
||||
cargo build # build all workspace members
|
||||
cargo test -p kordophone
|
||||
```
|
||||
|
||||
Build a specific crate:
|
||||
|
||||
```bash
|
||||
cargo build -p kordophone
|
||||
cargo build -p kordophoned --release
|
||||
```
|
||||
|
||||
## `kordophoned` (Client Daemon)
|
||||
|
||||
The daemon maintains a local cache, handles update cycles, and exposes IPC for GUI apps.
|
||||
|
||||
- Linux: exposes a D‑Bus service (see service file in `kordophoned/include`).
|
||||
- macOS: exposes an XPC service named `net.buzzert.kordophonecd`.
|
||||
|
||||
macOS XPC registration (manual during development):
|
||||
|
||||
```bash
|
||||
cd core/kordophoned
|
||||
launchctl load include/net.buzzert.kordophonecd.plist
|
||||
```
|
||||
|
||||
The macOS GUI app (`osx/`) can programmatically register this during launch; see `osx/README.md`.
|
||||
|
||||
### Packaging (RPM example)
|
||||
|
||||
`kordophoned` is configured for RPM packaging via `cargo-generate-rpm`.
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
strip -s target/release/kordophoned
|
||||
cargo generate-rpm
|
||||
```
|
||||
|
||||
## `kpcli` (CLI)
|
||||
|
||||
Useful for quick testing and interacting with the daemon/cache.
|
||||
|
||||
```bash
|
||||
cargo run -p kpcli -- --help
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- TLS/WebSocket: the `kordophone` crate includes `rustls` and installs a crypto provider at process start.
|
||||
- DB: `kordophone-db` includes Diesel migrations under `kordophone-db/migrations/`.
|
||||
|
||||
40
mock/README.md
Normal file
40
mock/README.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Kordophone Mock Server (Go)
|
||||
|
||||
A lightweight mock of the Kordophone macOS server for local development and tests. It emulates the REST API and updates stream, and seeds itself with sample conversations/messages/attachments.
|
||||
|
||||
## Build & Run
|
||||
|
||||
Requirements: Go 1.20+
|
||||
|
||||
```bash
|
||||
cd mock
|
||||
go run ./... # quick run
|
||||
|
||||
# or build a binary
|
||||
make # outputs ./kordophone-mock
|
||||
./kordophone-mock
|
||||
```
|
||||
|
||||
Flags:
|
||||
|
||||
- `--debug` — enable debug logging
|
||||
- `--auth` — require authentication (Bearer token via `/authenticate`)
|
||||
|
||||
Listens on `http://localhost:5738` by default.
|
||||
|
||||
## API Surface (mocked)
|
||||
|
||||
- `GET /version` — server version
|
||||
- `GET /status` — status (requires auth when enabled)
|
||||
- `GET /conversations` — list conversations
|
||||
- `GET /messages?guid=...&beforeDate=...&beforeMessageGUID=...&afterMessageGUID=...&limit=...` — list messages
|
||||
- `POST /authenticate` — exchange username/password for a bearer token (when `--auth`)
|
||||
- `POST /sendMessage` — send a message
|
||||
- `POST /markConversation?guid=...` — mark read
|
||||
- `GET /attachment?guid=...` — download attachment
|
||||
- `POST /uploadAttachment?filename=...` — upload attachment
|
||||
- `GET /pollUpdates?seq=...` — long‑poll for updates
|
||||
- `GET /updates` — WebSocket updates
|
||||
|
||||
Note: `/api/*` paths are redirected to the same endpoints for compatibility.
|
||||
|
||||
31
osx/README.md
Normal file
31
osx/README.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Kordophone macOS Client (Cocoa)
|
||||
|
||||
SwiftUI/Cocoa client for Kordophone on macOS. This app uses the Rust `core` library via the local client daemon (`kordophoned`) and communicates over XPC.
|
||||
|
||||
## Project
|
||||
|
||||
- Open `osx/kordophone2.xcodeproj` in Xcode.
|
||||
- Target bundle id: `net.buzzert.kordophone2`.
|
||||
|
||||
## XPC + Daemon
|
||||
|
||||
The macOS client talks to the `kordophoned` XPC service (`net.buzzert.kordophonecd`). During development, register the daemon with launchd:
|
||||
|
||||
```bash
|
||||
cd core/kordophoned
|
||||
launchctl load include/net.buzzert.kordophonecd.plist
|
||||
```
|
||||
|
||||
The app can also register programmatically using `SMAppService` (see inline comments in `XPC/XPCClient.swift`).
|
||||
|
||||
## Running
|
||||
|
||||
1. Ensure the XPC service is registered and the `kordophoned` binary is available (see `core/README.md`).
|
||||
2. Build and run the `kordophone2` app.
|
||||
3. Configure the app to point the daemon at your Kordophone server URL (mock or real).
|
||||
|
||||
## Notes
|
||||
|
||||
- Attachments are staged under the user’s temp directory (see `Attachments.swift`).
|
||||
- Entitlements and daemon files are included under `kordophone2/Daemon/` and `Supporting Files/`.
|
||||
|
||||
Reference in New Issue
Block a user