Files
simplex-chat/apps/ios
Evgeny @ SimpleX Chat c2d66c9d1d core, ios: complete XFTP uploads after the app leaves the foreground (#7966)
* core: delete agent file after every terminal XFTP upload event

* ios: spec for XFTP uploads during suspension

* core: pin simplexmq to evgeny-simplex fork for CI

* core: skip agent file deletion for XFTP errors without file ID

* ios: spec for counted XFTP uploads during suspension

* docs: plan for agent file deletion after XFTP uploads

* docs: revise plan for agent file deletion after XFTP uploads

* docs: revise plan wording for agent file deletion after XFTP uploads

* ios: spec wording for XFTP uploads during suspension

* core: pin simplexmq to the rewritten fork commit

* core: pin simplexmq with ended uploads excluded from suspension wait

* ios: suspend the app chat at once when the share sheet opens

* docs: plan decisions for the app yielding to the share extension

* core: verify agent file deletion for an item deleted during upload

* ios: spec wording for awaited XFTP uploads during suspension

* core: pin simplexmq with renamed upload wait functions and tests

* docs: plan wording, spec text and deletion test for agent files

* ios: suspend the app at once for the share sheet only while suspending

* docs: plan the narrowed share extension yielding

* docs: share extension wait, NSE and residual cases in plan and spec

* docs: plan tests for the remaining agent file deletion paths

* core: verify agent file deletion on the remaining upload paths

* core: pin simplexmq to the fork commit with merged master

* docs: plan line references after merging master and flow diagrams

* core: agent file deletion finalizer written with flip, as in the codebase

* ios: spec states the conditions of the share extension wait and the instant suspension

* docs: plan names the merged master base and the spec conditions

* core: pin simplexmq to the fork commit with the review fixes

* docs: spec and plan state when the share extension wait ends, link the simplexmq pull request, list the device test after app suspension

* core: pin simplexmq to the fork commit with the separate suspend timeout thread

* docs: spec and plan state that the share extension wait ends at the first check with both states suspended

* core: pin simplexmq master commit with the merged upload changes

* core, ios: test instant suspension on the share extension signal

* ios: deliver the share extension signal to the app in the setup wait test

* ios: await the delivery result outside the assertion

* ios: keep the app running until each file upload ends

* tests: record each upload fixture in its own test

* ios: restore the suspension of the app and the share extension of master

* tests: add the upload fixture files to record into

* tests: record upload responses and events for app tests

* core: update query plans

* tests: delete the uploaded item after its upload ends

* core: no error for upload events of a deleted file
2026-11-21 23:20:09 +00:00
..
2026-10-20 09:27:01 +01:00
2026-10-20 09:27:01 +01:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-10-20 09:27:01 +01:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-10-30 14:18:08 +00:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-10-30 14:18:08 +00:00
2026-10-20 09:27:01 +01:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00

SimpleX Chat iOS app

This file provides guidance when working with code in this repository.

iOS App Overview

The iOS app is a SwiftUI application that interfaces with the Haskell core library via FFI. It shares the SimpleXChat framework with two extensions: Notification Service Extension (NSE) for push notifications and Share Extension (SE) for sharing content from other apps.

Build & Development

Open SimpleX.xcodeproj in Xcode. The project has five targets:

  • SimpleX (iOS) - Main app (Bundle ID: chat.simplex.app)
  • SimpleXChat - Framework containing FFI bridge and shared types
  • SimpleX NSE - Notification Service Extension
  • SimpleX SE - Share Extension
  • Tests iOS - UI tests

Build and run via Xcode (Product > Build/Run). Tests run via Product > Test or:

xcodebuild test -scheme "SimpleX (iOS)" -destination 'platform=iOS Simulator,name=iPhone 15'

Deployment target: iOS 15.0+, Swift 5.0.

Architecture

Haskell Core Integration

The app calls the Haskell core library through C FFI defined in SimpleXChat/SimpleX.h:

  • chat_migrate_init_key() - Initialize/migrate database
  • chat_send_cmd_retry() - Send command to chat controller
  • chat_recv_msg_wait() - Receive messages from controller

Swift wrappers in SimpleXChat/API.swift:

  • chatMigrateInit() - Initialize chat controller
  • sendSimpleXCmd<R>() - Send typed commands and parse responses
  • recvSimpleXMsg<R>() - Receive typed messages

Haskell runtime initialization (SimpleXChat/hs_init.c) uses different memory configurations:

  • Main app: 64MB heap
  • NSE: 512KB heap (minimal footprint for background processing)
  • SE: 1MB heap

Pre-compiled Haskell libraries are in Libraries/{ios,mac,sim}/.

State Management

  • ChatModel (Shared/Model/ChatModel.swift) - Main singleton ObservableObject for app-wide state (chat list, active chat, users)
  • ItemsModel - Manages chat items within a selected chat (similar to Kotlin's ChatsContext)
  • AppTheme - Theme management and customization

App Structure

Entry point: Shared/SimpleXApp.swift

Key directories in Shared/:

  • Model/ - Data models and API layer (ChatModel.swift, SimpleXAPI.swift)
  • Views/ - SwiftUI views organized by feature:
    • ChatList/ - Chat list and user picker
    • Chat/ - Message display and composition
    • Call/ - VoIP call UI
    • UserSettings/ - App settings
    • LocalAuth/ - Passcode and biometric authentication
    • Database/ - Database initialization and migration

Shared Data Between Targets

All three targets share data via App Group (group.chat.simplex.app):

  • SimpleXChat/AppGroup.swift - GroupDefaults wrapper for typed shared preferences
  • Keychain for sensitive data: kcDatabasePassword, kcAppPassword, kcSelfDestructPassword

Key Types

Types are defined in SimpleXChat/:

  • ChatTypes.swift - User, Chat, Message, Group types
  • APITypes.swift - API request/response types

Commands follow ChatCmdProtocol (has cmdString property), sent as JSON through FFI.

Localization

31 languages supported. Localization files in SimpleX Localizations/.

Workflow:

  • Product > Export Localizations - Export XLIFF files
  • Product > Import Localizations - Import updated translations

SimpleX Assets

The app includes optional assets behind the SIMPLEX_ASSETS Swift compilation flag. Without setup, the app builds normally without them.

Setup

Create Local.xcconfig (gitignored) in the apps/ios/ directory:

SIMPLEX_ASSETS_DIR = /path/to/assets
SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) SIMPLEX_ASSETS

The copy script (scripts/ios/copy-assets.sh) runs as a build phase on each build but exits immediately if SIMPLEX_ASSETS is not set.

Updating assets

When source images change, regenerate resized images (requires ImageMagick):

cd path/to/assets && ./resize.sh

Background Capabilities

Configured in Info.plist:

  • Background modes: audio, fetch, remote-notification, voip
  • URL scheme: simplex:// for deep linking
  • BGTaskScheduler: chat.simplex.app.receive