forked from upstream-mirrors/quik
170 lines
9.4 KiB
Markdown
170 lines
9.4 KiB
Markdown
# QUIK — Remotrix Matrix bridge fork
|
|
|
|
An Android SMS messenger based on QUIK, with an integrated Remotrix service that bridges SMS messages to Matrix.
|
|
|
|
**Upstream:** [octoshrimpy/quik](https://github.com/octoshrimpy/quik).
|
|
**Fork repository:** [karol/quik](https://gitea.labus.uk/karol/quik).
|
|
|
|
[Fork purpose](#fork-purpose) · [Changes from upstream](#changes-from-upstream) · [Requirements](#requirements) · [Getting started](#getting-started) · [Configuration](#configuration) · [Usage](#usage) · [Development](#development) · [Upstream maintenance](#upstream-maintenance) · [Documentation](#documentation) · [Credits](#credits) · [License](#license)
|
|
|
|
## Fork purpose
|
|
|
|
The original Remotrix project was a standalone background bridge that required a separate, default SMS handler application. By deeply integrating Remotrix directly into Quik, we created a single, unified SMS application that offers a beautiful Material Design UI on the phone, while silently syncing all messages to your Matrix account (via Trixnity) in the background.
|
|
|
|
## Changes from upstream
|
|
|
|
- **Native Matrix Background Sync**: SMS messages sent or received on the phone are instantly bridged to your Matrix account.
|
|
- **Two-way Communication**: Messages sent from Matrix are instantly forwarded as standard SMS messages from the phone.
|
|
- **Coroutines Deadlock Fix**: Upgraded Room database dependencies to resolve fatal `SQLiteConnectionPool` deadlocks during the cryptographic key generation phases.
|
|
- **Enhanced Visual Formatting**: Matrix messages now use intuitive prefixes (🟢 for outgoing, 🔴 for incoming) to clearly distinguish participants without requiring AppService double puppeting.
|
|
- **Gitea Actions CI/CD**: Includes automated builds and automatic upstream fetching from the original Quik repository.
|
|
|
|
## Requirements
|
|
|
|
- An Android device with SMS support for sending and receiving messages.
|
|
- A Matrix homeserver, bridge account, and Manager ID for Matrix integration.
|
|
- JDK 17 and the Android SDK for local builds.
|
|
- A persistent signing key for Release builds; Debug builds do not need release credentials.
|
|
|
|
## Getting started
|
|
|
|
Download APKs from [this fork's Gitea releases](https://gitea.labus.uk/karol/quik/releases). For local development, run:
|
|
|
|
```bash
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
Debug APKs are written to `presentation/build/outputs/apk/debug/`. Debug builds use a separate application ID. Upstream download links in `README.upstream.md` distribute QUIK without this fork's Matrix integration.
|
|
|
|
## Configuration
|
|
|
|
In QUIK settings, open the Matrix login dialog, sign in with the bridge account, and set your Manager ID. For release signing configuration, see [Development](#development).
|
|
|
|
## Usage
|
|
|
|
### Management room
|
|
|
|
When you log into the application with your Matrix bot account (`@remotrix:yourserver.com`) and specify a Manager ID (`@you:yourserver.com`), the bot creates a dedicated **Management Room** and invites you.
|
|
From there, you can issue commands:
|
|
|
|
- `!new <phone_number>` - Opens a new Matrix room dedicated to chatting with that phone number.
|
|
- `!close` - Deletes a chat room.
|
|
- `!ping` - Checks bot latency.
|
|
- `!reload` - Restarts the background service.
|
|
|
|
Any non-command text sent in a dedicated phone number room will be sent as an SMS to that contact.
|
|
|
|
### Reset Matrix
|
|
|
|
In Quik settings, open the Matrix login dialog and select **Reset Matrix**.
|
|
Confirm the reset, remove the old rooms on your Matrix server, then sign in again.
|
|
The reset removes local Matrix accounts, room mappings, encryption stores and bridge logs;
|
|
SMS messages, Quik settings, the Manager ID and the backfill limit are preserved.
|
|
New rooms use contact names from Android, and SMS history is copied again up to the configured limit.
|
|
|
|
### History import
|
|
|
|
History import retries a failed message before advancing, with retry delays up to one minute.
|
|
Synapse room-creation limits still apply. There is no fixed delay after each successful message.
|
|
Progress is stored by native message type and ID, so identical SMS texts remain separate messages
|
|
and saved progress is skipped when an unfinished import resumes. Reset Matrix clears this progress.
|
|
The completion flag means all selected messages were handed to the persistent Matrix outbox
|
|
(or intentionally excluded by forwarding settings); outbox delivery remains managed by Trixnity.
|
|
Logcat reports progress and retry positions without logging SMS bodies or phone numbers.
|
|
|
|
Upgrading preserves an existing completed-import flag. It does not automatically replay old history:
|
|
older versions did not retain per-message progress, so replaying that history could create duplicates.
|
|
Checkpoint storage and the Matrix outbox use separate databases; an abrupt process/device failure
|
|
between enqueueing a message and saving its checkpoint can still replay that last message.
|
|
|
|
## Development
|
|
|
|
### Persistent release signing
|
|
|
|
Release APKs require the permanent signing key. Missing signing configuration fails the build;
|
|
release builds never fall back to a generated debug key. Pull requests build and test Debug
|
|
without release secrets and do not publish releases.
|
|
|
|
Gitea repository **Settings → Actions → Secrets** must contain:
|
|
|
|
- `ANDROID_KEYSTORE_BASE64`: base64-encoded permanent PKCS12 keystore.
|
|
- `ANDROID_KEYSTORE_PASSWORD`: keystore password.
|
|
- `ANDROID_KEY_ALIAS`: signing key alias.
|
|
- `ANDROID_KEY_PASSWORD`: private key password.
|
|
|
|
The public certificate and its SHA-256 fingerprint are tracked in `.gitea/release-signing.crt`
|
|
and `.gitea/release-signing.sha256`. CI checks the restored key and the finished Release APK
|
|
against this fingerprint before publishing. The temporary CI key is removed even after failure.
|
|
Do not regenerate the signing key between builds; back up the key and passwords securely.
|
|
The initial local backup is `.secrets/quik-release.p12` with credentials in
|
|
`.secrets/release-signing.json`. These private files are ignored by Git and must not be committed.
|
|
|
|
For a local Release build, set `ANDROID_KEYSTORE_PATH`, `ANDROID_KEYSTORE_PASSWORD`,
|
|
`ANDROID_KEY_ALIAS` and `ANDROID_KEY_PASSWORD`. Existing local `.gradle/.gradlerc` properties
|
|
and the legacy CI environment names are also supported. Debug APKs use a separate application ID
|
|
and are intended for development.
|
|
|
|
The former builds 50 and 51 used different disposable debug certificates. The new permanent key
|
|
cannot update either installation in place; migrating once to the new certificate requires a
|
|
reinstall. Subsequent Release updates keep the same signature.
|
|
|
|
### Builds and releases
|
|
|
|
The project uses Gitea Actions for CI/CD:
|
|
|
|
- `build.yml`: Runs tests and builds Debug APKs for pull requests to `master`. Pushes to `master` and `v*` tags also build signed Release APKs and publish a Gitea release after verification.
|
|
- `sync.yml`: Runs weekly to automatically fetch changes from the original `quik` upstream repository and merge them into our fork.
|
|
|
|
To build manually:
|
|
|
|
```bash
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
The APK will be available in `presentation/build/outputs/apk/debug/`.
|
|
|
|
### Automated release checks
|
|
|
|
The workflow pins JDK 17 so test and build tools use the same Java runtime.
|
|
Before building or publishing APKs, Gitea Actions runs Robolectric tests against the actual
|
|
`InjectionWorkerFactory`. They construct every worker type used by Quik and the Matrix bridge,
|
|
verify SMS/MMS dependency injection, and exercise the Matrix watcher's service-start intent.
|
|
These tests use simulated Android services and mocked repositories, without sending SMS or
|
|
connecting to Matrix. Matrix room creation, client shutdown, reset and history import also have
|
|
regression tests. Signing checks run separately.
|
|
|
|
Run the same runtime gate locally with JDK 17 and the Android SDK:
|
|
|
|
```sh
|
|
./gradlew :presentation:cleanTestDebugUnitTest :remotrix-sync:cleanTestDebugUnitTest :presentation:testDebugUnitTest :remotrix-sync:testDebugUnitTest
|
|
python3 .gitea/scripts/check_test_results.py
|
|
```
|
|
|
|
The gate rejects failures, missing required suites, and skipped critical tests. A failed gate
|
|
stops the workflow before publication. These tests cover known regression scenarios; they do
|
|
not replace testing the installed Release APK on Android devices.
|
|
|
|
## Upstream maintenance
|
|
|
|
The [sync workflow](.gitea/workflows/sync.yml) runs weekly and on manual dispatch, merging `master` from the configured Gitea upstream mirror. Merge or sync failures are reported by the workflow.
|
|
|
|
After each upstream merge, review SMS/Matrix forwarding, reset and history import behavior, and signing configuration. Run the regression checks described above. Keep this fork's README separate from the inherited documentation; refresh `README.upstream.md` from upstream when needed and retain its credits and license notices.
|
|
|
|
## Documentation
|
|
|
|
- [Inherited upstream README](README.upstream.md): retained from this checkout, with fork-specific release checks moved here and repository-relative contribution links corrected.
|
|
- [Upstream contribution guidelines](CONTRIBUTING.md).
|
|
- [Privacy notice](PRIVACY).
|
|
|
|
[README style guide](docs/README-STYLE.md).
|
|
|
|
## Credits
|
|
|
|
Development of the changes maintained in this fork was carried out to a significant extent with assistance from AI coding agents, in collaboration with the repository owner.
|
|
|
|
QUIK continues QKSMS and includes work by the QUIK, Remotrix, and android-smsmms contributors. See [upstream acknowledgments](README.upstream.md#thank-you). Fork-specific issues belong in this fork's issue tracker.
|
|
|
|
## License
|
|
|
|
GNU General Public License v3.0; see [LICENSE](LICENSE). Upstream code and notices retain their original attribution.
|