489 lines
34 KiB
Typst
489 lines
34 KiB
Typst
#import "../style.typ"
|
||
#set heading(numbering: "1.1")
|
||
|
||
= Implementacja <implementacja>
|
||
|
||
W poniższym rozdziale opiszę specyfikację wymagań dla projektowanej aplikacji do współtworzenia notatek w architekturze peer to peer oraz jej pełną implementację. Celem wymagań jest określenie zakresu funkcjonalności oraz ograniczeń technologicznych, których będę się trzymać w ramach proponowanej implementacji. Wyodrębnię dwóch aktorów:
|
||
|
||
- Użytkownika - osoba zarządzająca notatkami przez interfejs graficzny zaimplementowany w ramach implementacji,
|
||
- Klient - instancja implementowanej aplikacji na urządzeniu fizycznym.
|
||
|
||
Same wymagania zostały podzielone odpowiednio na wymagania funkcjonalne i niefunkcjonalne.
|
||
|
||
== Wymagania funkcjonalne
|
||
- System musi umożliwiać rozgłaszanie swojej obecności w sieci lokalnej, by móc zostać wykrytym przez innych klientów.
|
||
- System musi umożliwiać wyszukiwanie innych aktywnych klientów znajdujących się w zakresie lokalnego otoczenia oraz lokalnej sieci.
|
||
- System musi pozwalać na wysyłanie zaproszeń do połączenia się z wykrytymi klientami.
|
||
- System musi na bieżąco wyświetlać listę aktualnie połączonych klientów.
|
||
|
||
- System musi umożliwiać utworzenie nowej notatki tekstowej.
|
||
- System musi umożliwiać edycję treści istniejącej notatki.
|
||
- System musi umożliwiać trwałe usunięcie notatki.
|
||
- System musi automatycznie tworzyć unikalny identyfikator oraz znacznik czasowy dla nowych notatek.
|
||
- System musi pozwalać na zdefiniowanie tytułu notatki, będącego niezależnym parametrem od treści notatki.
|
||
|
||
- System musi enkodować strukturę danych notatki do formatu umożliwiającego przesył notatki do połączonych klientów.
|
||
- System musi dekodować otrzymane zakodowane dane o notatce i przekształcić je w natywny obiekt reprezentujący notatkę w systemie.
|
||
- System musi automatycznie rozsyłać zaktualizowaną treść notatki do wszystkich aktualnie połączonych klientów w jak najkrótszym czasie od wykrycia zmian.
|
||
- System musi nadpisać istniejącą notatkę nowo otrzymaną kopią, gdy obie posiadają ten sam identyfikator, ale otrzymana kopia zawiera nowszy znacznik czasowy.
|
||
|
||
- System musi zapisywać wszystkie notatki w trwałej pamięci urządzenia.
|
||
- System musi odświeżać interfejs z listą notatek w czasie rzeczywistym.
|
||
|
||
== Wymagania niefunkcjonalne
|
||
- System musi wspierać urządzenia mobilne firmy Apple z zainstalowanymi systemami operacyjnymi iOS lub iPadOS w wersji 18.0 lub wyższej.
|
||
- Kod źródłowy powinien być napisany w języku Swift z wykorzystaniem deklaratywnego frameworka do budowy interfejsów graficznych - SwiftUI.
|
||
- Operacje zapisu do plików oraz procesy sieciowe muszą być wykonywane poza głównym wątkiem - wątkiem obsługującym interfejs graficzny aplikacji.
|
||
- Czas propagacji zmian w notatce do innego połączonego klienta nie powinien wynosić więcej niż 1 sekunda.
|
||
- System musi obsłużyć przypadek zerwania połączenia, bez uszkodzenia notatki oraz rzucania wyjątków uniemożliwiających dalsze funkcjonowanie systemu.
|
||
- System musi zapewnić szyfrowaną komunikację między klientami.
|
||
- Interfejs użytkownika musi być responsywny i dostosowywać się do różnych rozmiarów ekranów i ich orientacji w zakresie urządzeń tworzonych przez Apple.
|
||
- Wygląd aplikacji powinien spełniać oficjalne wytyczne projektowe Apple Human Interface Guideliens.
|
||
- System powinien automatycznie dostosowywać paletę kolorów interfejsu graficznego do aktualnie ustawionego motywu systemowego.
|
||
|
||
== Projekt architektury systemu <projekt>
|
||
Przygotowana implementacja bazuje na architekturze Model-View. Jest to podejście, gdzie cała logika biznesowa jest zawarta w modelach, które bezpośrednio są przekazywane do warstwy prezentacji (View). Na tej warstwie jest wykonywane odpowiednie formatowanie danych, gdzie też brane pod uwagę są preferencje zapisu i językowe użytkownika. Model-View to uproszczony wariant popularnej w aplikacjach mobilnych architektury Model-View-ViewModel (MVVM), gdzie ViewModel jest warstwą zajmującą się przekształcaniem modelów biznesowych na gotowe do prezentacji obiekty. Warstwa View wtedy zajmuje się przede wszystkim definiowaniem struktury interfejsu użytkownika oraz logiką związaną z dostępnością (wsparcie dla funkcjonalności czytników ekranów, skalowaniem interfejsu). Przygotowana implementacja nie zawiera złożonej logiki prezentacji ani rozbudowanego graficznego interfejsu użytkownika, więc w celu uproszczenia kodu zdecydowałem się na porzucenie użycia warstwy ViewModelu.
|
||
|
||
Warstwa prezentacji aplikacji opisująca początkowy interfejs użytkownika jest zaimplementowana w `AllNotesScreen`. Ekran jest widoczny dla użytkownika, gdy ustawił swoją nazwę użytkownika w sieci peer-to-peer. Składa się z listy podzielonej na dwie sekcje - notatek których użytkownik jest autorem, oraz notatek do których użytkownik został zaproszony. Nad listą znajduje się przycisk stworzenia nowej notatki. Naciśnięcie na którąkolwiek z istniejących notatek prowadzi do otwarcia jej zawartości. W zależności od tego, czy użytkownik jest właścicielem danej notatki czy współtwórcą, interfejsem do edycji tej notatki są odpowiednio obiekty `NoteEditorScreen` oraz `SharedNoteEditor`. Z ekranu `NoteEditorScreen` możemy przejść do `ManageMembersScreen`, który jest listą użytkowników zaproszonych i możliwych do zaproszenia do edytowania aktualnej notatki.
|
||
|
||
== Model danych
|
||
Program 3.1 przedstawia podstawowy obiekt reprezentujący notatkę w systemie plików - `Note`. Składa się on z URL (Universal Resource Locator), czyli ścieżki prowadzącej do pełnej zawartości notatki użytkownika, która jest przechowywana w pliku tekstowym o rozszerzeniu `txt`. Dodatkowo przechowujemy w tym obiekcie jeszcze `name`, które pełni funkcję ułatwionego dostępu do przyjaznej nazwy, jednocześnie będąc nazwą pliku w lokalnym systemie plików oraz przyjazną nazwą prezentowaną w liście notatek do których użytkownik został zaproszony. Obiekt implementuje protokół `Identifiable`, który gwarantuje możliwość identyfikacji obiektu w zbiorze zawierającym wiele jego instancji, np. w tablicy. Ta cecha jest wymagana i wykorzystywana przez SwiftUI, by móc rozróżniać rodzaje zmian na komponentach interfejsów graficznych zawierających wiele kopii takiego obiektu, np. `List` lub `ForEach`. Umożliwia to dokonanie decyzji co do sposobu animacji zmian na ekranie użytkownika, ponieważ framework będzie mógł rozróżnić usunięcie i wstawienie nowego obiektu, od zmiany parametrów tej samej instancji.
|
||
|
||
#let note_struct = [```swift
|
||
struct Note: Identifiable {
|
||
var id: URL { path }
|
||
|
||
let name: String
|
||
let path: URL
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_struct,
|
||
kind: raw,
|
||
caption: [Definicja obiektu notatki],
|
||
)
|
||
|
||
Program 3.2 przedstawia `NoteMessage` - obiekt zawierający zawartość notatki, którą wysyłamy do użytkowników, którzy przyjęli zaproszenie do edycji notatki. Znajdziemy w niej pola `SenderID`, które jest identyfikatorem właściciela notatki oraz `content`, czyli właściwą zawartość notatki. Jest ona również używana do wysyłania każdej aktualizacji do wszystkich użytkowników. Obiekt implementuje protokół `Codable`, który jest uniwersalnym interfejsem kodowania danych. Daje to nam wbudowane wsparcie kodowowania do formatów JSON i XML. Mamy możliwość również pisania własnych koderów, które umożliwią zamianę obiektów implementujących `Codable` do wybranych przez nas, innych formatów danych.
|
||
|
||
#let note_message_struct = [```swift
|
||
struct NoteMessage: Codable {
|
||
let senderID: String
|
||
let content: String
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_message_struct,
|
||
kind: raw,
|
||
caption: [Definicja obiektu notatki wysyłanego między użytkownikami],
|
||
)
|
||
|
||
Do reprezentacji zaproszeń stworzyłem obiekt `NoteInvitation` przedstawiony w programie 3.3. Przechowuje on informacje potrzebne do obsługi całego procesu zaproszeń między użytkownikami systemu. Składa się z `invitatorID`, który jest wyspecjalizowanym obiektem frameworku `MultipeerConnectivity` i umożliwia identyfikację użytkownika w czasie komunikacji peer to peer. `note` to obiekt reprezentujący notatkę, którą otrzymujemy w zaproszeniu. Składa się on z tytułu i treści, które były aktualne w momencie zapraszania użytkownika. Ostatnim i jednocześnie prywatnym parametrem jest `invitationHandler`, który jest typem funkcji przyjmującej wartość boolowską (prawda/fałsz). Jest on wykorzystywany do wstrzyknięcia logiki akceptacji notatki, która wymaga kilku operacji w logice klasy obsługującej przyjmowanie zaproszeń. Dzięki takiemu podejściu tworzymy luźną zależność do skomplikowanego obiektu na dalszych etapach systemu. `NoteInvitation` zawiera również metody `accept()` oraz `decline()`, które odpowiadają za wykonanie akcji zaproszenia, które pod spodem odpowiednio używają parametru `invitationHandler`, który można wykonać tylko raz, ze względu na specyfikę `Multipeer Connectivity`, a następnie usuwamy go z pamięci.
|
||
|
||
#let note_invitation_struct = [```swift
|
||
struct NoteInvitation: Identifiable {
|
||
struct NoteContent: Codable {
|
||
let title: String
|
||
let noteSnapshot: String
|
||
}
|
||
|
||
var id: MCPeerID { invitatorID }
|
||
var noteName: String { note.title }
|
||
let invitatorID: MCPeerID
|
||
let note: NoteContent
|
||
private var invitationHandler: ((Bool) -> Void)?
|
||
|
||
init(
|
||
invitatorID: MCPeerID,
|
||
note: NoteContent,
|
||
invitationHandler: ((Bool) -> Void)? = nil
|
||
) {
|
||
self.invitatorID = invitatorID
|
||
self.note = note
|
||
self.invitationHandler = invitationHandler
|
||
}
|
||
|
||
mutating func accept() {
|
||
invitationHandler?(true)
|
||
invitationHandler = nil
|
||
}
|
||
|
||
mutating func decline() {
|
||
invitationHandler?(false)
|
||
invitationHandler = nil
|
||
}
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_invitation_struct,
|
||
kind: raw,
|
||
caption: [Definicja obiektu reprezentującego zaproszenie do edycji notatki],
|
||
)
|
||
|
||
Ostatnim obiektem jest struktura `Peer` przedstawiona w programie 3.4, która jest opisem aktualnego stanu połączenia wykrytego innej instancji systemu w pobliżu użytkownika. Składa się z wartości enumerowanej opisującej stan połączenia wraz z identyfikatorem użytkownika w sieci peer to peer. Implementuje ona protokół `Identifiable`, by móc zostać poprawnie użyta do rysowania listy dostępnych klientów w pobliżu użytkownika.
|
||
|
||
#let peer_struct = [```swift
|
||
struct Peer: Identifiable {
|
||
enum ConnectionState {
|
||
case available
|
||
case joined
|
||
case rejected
|
||
case invitationPending
|
||
}
|
||
|
||
var id: String { mcPeer.displayName }
|
||
let mcPeer: MCPeerID
|
||
var state: ConnectionState
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
peer_struct,
|
||
kind: raw,
|
||
caption: [Definicja obiektu reprezentującego widocznego klienta],
|
||
)
|
||
|
||
== Warstwa sieciowa i komunikacja P2P
|
||
Całość komunikacji między urządzeniami odbywa się z wykorzystaniem frameworka Multipeer Connectivity. Klient twórcy notatki pełni rolę serwera, a pozostali użytkownicy, po uprzednim zaproszeniu, mogą dołączyć do edycji notatki, wysyłać swoje zmiany jak i odbierać zmiany, które dystrybuuje serwer.
|
||
|
||
== Odkrywanie innych urządzeń
|
||
Obiekt reprezentujący serwer został nazwany `NoteEditingSessionServer`, który dziedziczy właściowści po klasie `NSObject`, która jest uniwersalną implementacją wielu zachowań, które są wymagane od frameworków udostępnianych przez Apple, które zostały napisane w języku Objective-C. Jego konstruktor, przedstawiony w programie 3.5, w przyjmowanych argumentach oczekuje tylko obiektu `OwnPeer`, który będzie wykorzystywany do identyfikacji instancji aplikacji u innych klientów. Sama implementacja konstruktora tworzy nową sesję `MCSession`; obiekt `MCNearbyServiceBrowser`, który odpowiada za wykrywanie pobliskich klientów. Finalnie przypisuje referencję do samego siebie jako parametr `delegate` dla utworzonych `MCSession` i `MCNearbyServiceBrowser`. Pozwala nam to zaimplementować metody, które będą wykorzystywane wewnątrz tych obiektów do komunikacji z innymi użytkownikami. Protokoły delegujące dla wspomnianych obiektów nazywają się odpowiednio `MCSessionDelegate` oraz `MCNearbyServiceBrowserDelegate`. Moja implementacja tych protokołów zostanie przedstawiona w dalszej części pracy.
|
||
|
||
#let note_editing_session_server_init = [```swift
|
||
init(peer: OwnPeer) {
|
||
ownPeer = peer
|
||
browser = .init(peer: peer.peer, serviceType: "peered")
|
||
session = .init(peer: peer.peer, securityIdentity: nil, encryptionPreference: .required)
|
||
super.init() // wykonuje pozostałą część
|
||
browser.delegate = self //
|
||
session.delegate = self
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_session_server_init,
|
||
kind: raw,
|
||
caption: [Implementacja konstruktora obiektu NoteEditingSessionServer],
|
||
)
|
||
|
||
W momencie, gdy autor notatki otworzy ekran edycji, wykonuje się metoda `startServer()`, która wywołuje metodę `startBrowsingForPeers()` obiektu `MCNearbyServiceBrowser`. Opuszczenie ekranu edycji wywołuje metodę `stopServer()`, która wywołuje analogiczną metodę `stopBrowsingForPeers()` oraz zatrzymuje sesję poprzez wywołanie metody `disconnect()` obiektu `MCSession`. Obie metody zostały przedstawione w programie 3.6.
|
||
|
||
#let note_editing_session_server_edge_lifecycle = [```swift
|
||
func startServer() {
|
||
browser.startBrowsingForPeers()
|
||
}
|
||
|
||
func stopServer() {
|
||
browser.stopBrowsingForPeers()
|
||
session.disconnect()
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_session_server_edge_lifecycle,
|
||
kind: raw,
|
||
caption: [Implementacja metod odpowiedzialnych za nasłuchiwanie na dostępnych klientów],
|
||
)
|
||
|
||
Obiekt `browser` w momencie wykrycia nowego użytkownika w pobliżu, wywołuje naszą metodę o nazwie `browser()`, która przyjmuje wszystkie potrzebne informacje o znalezionym użytkowniku. Implementacja mojego systemu, jak zostało to przedstawione w programie 3.7, następnie upewnia się czy odkryty użytkownik nie jest jednocześnie autorem notatki, co jest znanym błędem w Multipeer Connectivity. Następnie po udanej weryfikacji dodajemy nowy obiekt dostępnego użytkownika do tablicy na podstawie której jest budowany interfejs z listą dostępnych użytkowników.
|
||
|
||
#let note_editing_session_server_browser_found_peer = [```swift
|
||
func browser(
|
||
_ browser: MCNearbyServiceBrowser,
|
||
foundPeer peerID: MCPeerID,
|
||
withDiscoveryInfo info: [String: String]?
|
||
) {
|
||
guard !visiblePeers.contains(where: { $0.mcPeer == peerID }) && peerID.displayName != ownPeer.peer.displayName else { return }
|
||
DispatchQueue.main.async {
|
||
self.visiblePeers.append(Peer(mcPeer: peerID, state: .available))
|
||
}
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_session_server_browser_found_peer,
|
||
kind: raw,
|
||
caption: [Implementacja metody browser wywoływanej w przypadku wykrycia innego klienta],
|
||
)
|
||
|
||
W sytuacji gdy użytkownik straci połączenie z połączonym klientem, następuje usunięcie jego identyfikatora z listy, poprzez wywołanie metody o takiej samej nazwie, ale z parametrami wskazującymi na scenariusz zgubienia klienta, tak jak zostało to zapisane w programie 3.8.
|
||
|
||
#let note_editing_session_server_browser_lost_peer = [```swift
|
||
func browser(_ browser: MCNearbyServiceBrowser, lostPeer peerID: MCPeerID) {
|
||
DispatchQueue.main.async {
|
||
guard let peerIdx = self.visiblePeers.firstIndex(where: { $0.mcPeer == peerID }) else { return }
|
||
self.visiblePeers.remove(at: peerIdx)
|
||
}
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_session_server_browser_lost_peer,
|
||
kind: raw,
|
||
caption: [Implementacja metody browser wywoływanej gdy aplikacja utraci połączenie z wykrytym klientem],
|
||
)
|
||
|
||
Każda modyfikacja obiektów klasy w tym wypadku musi zostać wywołana na tym samym wątku, ponieważ Multipeer Connectivity nie gwarantuje, że kod będzie się wykonał zawsze na tym samym wątku. Wybrałem wątek główny, ze względu na bezpośrednie użycie właściwości klasy wewnątrz obiektów odpowiedzialnych za budowę interfejsu użytkownika.
|
||
|
||
Program 3.9 przedstawia część systemu, gdzie o stanie połączenia z innymi klientami system jest informowany przez wykonanie metody `session` z parametrami zawierającymi informację o stanie, który jest reprezentowany przez typ enumeracji, obiekt sesji oraz identyfikator klienta, których ten stan połączenia dotyczy. Na podstawie tych argumentów, aplikacja aktualizuje tablicę `visiblePeers`.
|
||
|
||
#let note_editing_session_server_session_peer_did_change_state = [```swift
|
||
func session(
|
||
_ session: MCSession,
|
||
peer peerID: MCPeerID,
|
||
didChange state: MCSessionState
|
||
) {
|
||
DispatchQueue.main.async {
|
||
guard let idx = self.visiblePeers.firstIndex(where: { $0.mcPeer == peerID }) else { return }
|
||
switch state {
|
||
case .connected:
|
||
self.visiblePeers[idx].state = .joined
|
||
case .notConnected:
|
||
let currentState = self.visiblePeers[idx].state
|
||
if currentState == .invitationPending || currentState == .joined {
|
||
self.visiblePeers[idx].state = .rejected
|
||
}
|
||
default:
|
||
break
|
||
}
|
||
}
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_session_server_session_peer_did_change_state,
|
||
kind: raw,
|
||
caption: [Implementacja metody session wywoływanej w przypadku zmiany stanu połączenia z konkretnym klientem],
|
||
)
|
||
|
||
Przechodząc do implementacji klienta, całość jest reprezentowana przez obiekt `NoteEditingSessionClient`. Jego konstruktor, obecny w programie 3.10, przyjmuje tylko identyfikator użytkownika, który jest typem `MCPeerID`, a implementacja obejmuje również stworzenie instancji `MCSession` do wykorzystania w trakcie połączenia z serwerem oraz instancji `MCNearbyServiceAdvertiser`, która propaguje informacje o kliencie do wszystkich innych klientów w pobliżu. Do obu obiektów przypisujemy obiekt delegujący, który będzie właśnie utworzoną instancją `NoteEditingSessionClient`. Dla `MCNearbyServiceAdvertiser` obiekt delegującego musi implementować protokół `MCNearbyServiceAdvertiserDelegate`.
|
||
|
||
#let note_editing_session_client_init = [```swift
|
||
init(peer: MCPeerID) {
|
||
ownPeer = peer
|
||
session = MCSession(
|
||
peer: peer,
|
||
securityIdentity: nil,
|
||
encryptionPreference: .required
|
||
)
|
||
advertiser = MCNearbyServiceAdvertiser(
|
||
peer: peer,
|
||
discoveryInfo: [:],
|
||
serviceType: "peered"
|
||
)
|
||
super.init()
|
||
advertiser.delegate = self
|
||
session.delegate = self
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_session_client_init,
|
||
kind: raw,
|
||
caption: [Implementacja konstruktora obiektu NoteEditingSessionClient],
|
||
)
|
||
|
||
Instancja `NoteEditingSessionClient` jest tworzona już przy pierwszym uruchomieniu aplikacji. Po utworzeniu przez użytkownika przyjaznej nazwy, która będzie używana do identyfikacji, w tle wywoływana jest metoda `startBrowsingForNotes()`, która wywołuje `startAdvertisingPeer()` obiektu `advertiser`. Przed rozpoczęciem nasłuchiwania aplikacja wywołuje również `stopBrowsingForNotes()`, by zatrzymać nasłuchiwanie, jeśli wcześniej było ono rozpoczęte, oraz zatrzymuje działanie obiektu `MCSession`, by zamknąć ewentualnie istniejącą sesję edycji notatki. Obie metody zostały przedstawione w programie 3.11.
|
||
|
||
#let note_editing_session_client_edge_lifecycle = [```swift
|
||
func startBrowsingForNotes() {
|
||
advertiser.startAdvertisingPeer()
|
||
}
|
||
|
||
func stopBrowsingForNotes() {
|
||
advertiser.stopAdvertisingPeer()
|
||
session.disconnect()
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_session_client_edge_lifecycle,
|
||
kind: raw,
|
||
caption: [Implementacja metod odpowiedzialnych za nasłuchiwanie na dostępne sesje edycji notatek],
|
||
)
|
||
|
||
Program 3.12 przedstawia jedyną metodę wymaganą przez protokół `MCNearbyServiceAdvertiserDelegate` - nazywa się `advertiser()` i w argumentach przyjmuje informację o otrzymanym zaproszeniu i metadanych jakie to zaproszenie zawierało. Aplikacja próbuje zdekodować migawkę notatki, a następnie konstruuje obiekt `NoteInvitation` i umieszcza go w tablicy `invitations`. Umieszczenie w tablicy trzeba wykonać na głównym wątku, ponieważ, analogicznie jak w wypadku implementacji `MCNearbyServiceBrowserDelegate`, nie mamy gwarancji na jakim wątku będzie wykonywała się ta metoda.
|
||
|
||
#let note_editing_client_advertiser_did_receive_invitation = [```swift
|
||
func advertiser(
|
||
_ advertiser: MCNearbyServiceAdvertiser,
|
||
didReceiveInvitationFromPeer peerID: MCPeerID,
|
||
withContext context: Data?,
|
||
invitationHandler: @escaping (Bool, MCSession?) -> Void
|
||
) {
|
||
guard
|
||
let context,
|
||
let noteContent = try? JSONDecoder().decode(NoteInvitation.NoteContent.self, from: context)
|
||
else { return }
|
||
|
||
DispatchQueue.main.async {
|
||
self.invitations.append(
|
||
.init(
|
||
invitatorID: peerID,
|
||
note: noteContent,
|
||
invitationHandler: { [weak self, invitationHandler] accepted in
|
||
guard let self else { return }
|
||
invitationHandler(accepted, self.session)
|
||
DispatchQueue.main.async {
|
||
self.invitations.removeAll { $0.id == peerID }
|
||
}
|
||
}
|
||
)
|
||
)
|
||
}
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_client_advertiser_did_receive_invitation,
|
||
kind: raw,
|
||
caption: [Implementacja metody advertiser wywoływanej podczas otrzymania zaproszenia do sesji],
|
||
)
|
||
|
||
== Transportowanie danych
|
||
|
||
W wysyłanym zaproszeniu wysyłamy w metadanych migawkę notatki zawierającą jej tytuł oraz ostatnio dostępną treść. Migawka jest kodowana w formacie JSON bazując na strukturze `NoteContent`. Przykładowym poprawnym zapisem JSON tej struktury jest przykład w programie 3.13.
|
||
|
||
#let note_content_json_representation = [```json
|
||
{
|
||
"title": "My new note",
|
||
"noteSnapshot": "Lorem Ipsum."
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_content_json_representation,
|
||
kind: raw,
|
||
caption: [Reprezentacja obiektu NoteContent w zapisie JSON],
|
||
)
|
||
|
||
Po stronie klienta, każda zmiana jest ogłaszana serwerowi poprzez wywołanie metody `send()` obiektu `NoteEditingSessionClient`, zapisaną w programie 3.14, która przyjmuje identyfikator użytkownika do które ma wiadomość trafić oraz całą zawartość notatki. Jej implementacja zamienia notatkę wraz z identyfikatorem w typ `NoteMessage`, następnie koduje ją do formatu JSON, finalnie próbuje ją wysłać do określonego użytkownika.
|
||
|
||
#let note_editing_session_client_send_note = [```swift
|
||
func send(note: String, to peer: MCPeerID) {
|
||
let message = NoteMessage(senderID: ownPeer.displayName, content: note)
|
||
guard let data = try? JSONEncoder().encode(message) else { return }
|
||
try? session.send(data, toPeers: [peer], with: .reliable)
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_editing_session_client_send_note,
|
||
kind: raw,
|
||
caption: [Implementacja metody send wysyłającej kopię notatki do serwera],
|
||
)
|
||
|
||
Przykładowy zapis instancji obiektu `NoteMessage` wygląda tak jak w programie 3.15:
|
||
|
||
#let note_message_json_representation = [```json
|
||
{
|
||
"senderID": "User2",
|
||
"content": "Lorem Ipsum Test"
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
note_message_json_representation,
|
||
kind: raw,
|
||
caption: [Reprezentacja obiektu NoteMessage w zapisie JSON],
|
||
)
|
||
|
||
Po tym jak serwer odbierze wysłaną wiadomość, wywoływana jest metoda `session`, widoczna w programie 3.16, która w argumentach przekazuje zakodowane dane, sesję serwera oraz identyfikator użytkownika, który wysłał załączone dane. Po udanym zdekodowaniu danych, wybieramy wszystkich użytkowników, którzy dołączyli do sesji edycji notatki i wysyłamy do nich kopię otrzymanej wiadomości, a serwer dodatkowo wysyła identyczną kopię do warstwy prezentacji.
|
||
|
||
|
||
#let code_session_did_receive_data_server = [```swift
|
||
func session(_ session: MCSession, didReceive data: Data, fromPeer peerID: MCPeerID) {
|
||
guard let message = try? JSONDecoder().decode(NoteMessage.self, from: data) else { return }
|
||
let otherPeers = session.connectedPeers.filter { $0 != peerID }
|
||
|
||
if !otherPeers.isEmpty {
|
||
try? session.send(data, toPeers: otherPeers, with: .reliable)
|
||
}
|
||
|
||
DispatchQueue.main.async {
|
||
self.noteChangesEmitter.send(message)
|
||
}
|
||
}
|
||
```]
|
||
|
||
#figure(
|
||
code_session_did_receive_data_server,
|
||
kind: raw,
|
||
caption: [Implementacja metody session do otrzymywania danych od innych klientów],
|
||
)
|
||
|
||
== Algorytm rozwiązywania konfliktów
|
||
|
||
Rozwiązywanie konfliktów jest dokonywane na podstawie strategii Last Writer Wins, gdzie ostatnio otrzymana wiadomość nadpisuje zawartość pozostałych kopii. W przypadku nanoszenia zmian na interfejs użytkownika, wykorzystałem natywną obsługę zmiany tekstu przez systemowy kompoent `TextEditor`, który w większości wypadków potrafi sobie poradzić czy prostych podmianach zawartości tekstu.
|
||
|
||
Zrezygnowałem z implementacji struktur danych CRDT ze względu na bardzo wysoki koszt implementacji, ponieważ oprócz samych struktur, musiałbym napisać własną implementację obsługi podmiany tekstu i aktualizacji kursora w edytorze tekstowym, co znacznie wykracza poza zakres tej pracy.
|
||
|
||
== Środowisko developerskie i stack technologiczny
|
||
|
||
Uruchomienie projektu wymaga posiadania komputera Macintosh z systemem operacyjnym macOS w wersji 26.0 (Tahoe) oraz środowisko programistyczne Xcode w wersji 26.0. Do uruchomienia aplikacji potrzebne jest założenie konta Apple ID i zaakceptowania warunków użytkowania konta deweloperskiego, dzięki któremu można wygenerować certyfikat, którego potrzebuje Xcode do zbudowania aplikacji.
|
||
|
||
Aplikacja wykorzystuje framework SwiftUI do budowania warstwy prezentacji. Jest to deklaratywny, wieloplatformowy framework między innymi dostarczający mechanizmy, które zostały wykorzystane w ramach tej pracy:
|
||
- automatycznego odświeżania interfejsu na podstawie nasłuchiwania na zmiany modelów danych
|
||
- automatycznego zapisu prymitywnych danych na dysku
|
||
- wstrzykiwania zależności wgłąb hierarchii interfejsu
|
||
- zaawansowanych wzorców stosowanych w tworzeniu dobrych doświadczeń użytkownika - np. wysuwalne panele (bottom sheets).
|
||
|
||
Kluczowym frameworkiem w budowaniu tej aplikacji jest Multipeer Connectivity, który zapewniał ułatwioną konfigurację całej komunikacji między pobliskimi użytkownikami. Pomocniczymi bibliotekami są `Foundation` oraz `Combine`.
|
||
|
||
`Foundation` daje dostęp do złożonych, ale bardzo często wykorzystywanych typów i funkcji w Swifcie - `URL`, `FileManager`, `JSONDecoder`, `JSONEncoder`.
|
||
|
||
`Combine` jest biblioteką dodającą programowanie reaktywne do Swifta, ale również jako pierwsza zapewniła mechanizmy komunikowania zmian w modelach danych do widoków implementowanych w SwiftUI. Moja praca wykorzystywała przede wszystkim obiekty `PassthroughSubjects`, które służyły za obiekty emitujące każde nowo otrzymane dane od innych użytkowników.
|
||
|
||
== Interfejs użytkownika
|
||
|
||
Aplikacja po uruchomieniu przez użytkownika który już ustawił swoją nazwę, pokazuje ekran główny, zaprezentowany na rysunku 3.1, który pogrubioną czcionką o dużym rozmiarze pokazuje nazwę aplikacji - "Peered". Na prawo do góry od napisu znajdziemy przycisk "Create note", który po naciśnięciu dodaje nową notatkę do listy "Your notes". Główną zawartością ekranu jest lista notatek podzielona na dwie sekcje - "Your notes" zawierająca notatki przechowywane w pamięci trwałej urządzenia, oraz "External notes" - notatki które aktualnie udostępnia inny klient w pobliżu urządzenia użytkownika. Po naciśnięciu na wiersz z nazwą notatki z sekcji "Your notes", przejdziemy do ekranu edycji własnej notatki przedstawionego na rysunku 3.2. Ten ekran, oprócz edytora tekstu, na samej górze posiada przycisk "Manage members", który pokazuje ekran zarządzania użytkownikami notatki, widoczny na rysunku 3.3. Możemy na nim zobaczyć listę widocznych użytkowników w pobliżu oraz możliwą akcję do wykonania. Jeśli użytkownik jest widoczny, ale nie został zaproszony, możemy zobaczyć przycisk "Invite". W pozostałych wypadkach widzimy teksty zależne od stanu połączenia - użytkownik, który dołączył będzie miał "Joined". Oczekujący na akceptację będą mieli "Invitation pending", a pozostali "Rejected". Po naciśnięciu na wiersz z nazwą notatki z sekcji "External notes", przejdziemy do ekranu edycji notatki innego użytkownika, gdzie na ekranie będziemy mieli wyłącznie dostęp do edytora tekstu, co można zobaczyć na rysunku 3.4. Jeśli użytkownik nie ustawił jeszcze swojej nazwy w aplikacji, od razu po uruchomieniu aplikacji pokazuje się ekran nadania nazwy użytkownika, widoczny na rysunku 3.5.
|
||
|
||
Jeśli aplikacja została dopiero zainstalowana, system pokaże też monit użytkownikowi z pytaniem, czy chce aby aplikacja otrzymała dostęp do sieci lokalnej, co zostało przedstawione na rysunku 3.6. Jest to obowiązkowa zgoda dla użytkownika, bez której aplikacja nie będzie w stanie komunikować się z innymi urządzeniami.
|
||
|
||
#figure(
|
||
image("../Pictures/AllNotesScreen.jpeg", height: 95%),
|
||
kind: image,
|
||
caption: "Ekran główny aplikacji",
|
||
)
|
||
#figure(
|
||
image("../Pictures/NoteEditorScreen.jpeg", height: 95%),
|
||
kind: image,
|
||
caption: "Ekran edycji własnej notatki",
|
||
)
|
||
#figure(
|
||
image("../Pictures/ManageMembersScreen.jpeg", height: 95%),
|
||
kind: image,
|
||
caption: "Ekran zarządzania użytkownikami notatki",
|
||
)
|
||
#figure(
|
||
image("../Pictures/SharedEditorScreen.jpeg", height: 95%),
|
||
kind: image,
|
||
caption: "Ekran edycji notatki innego użytkownika",
|
||
)
|
||
#figure(
|
||
image("../Pictures/SetUsernameScreen.jpeg", height: 95%),
|
||
kind: image,
|
||
caption: "Ekran nadania nazwy użytkownika",
|
||
)
|
||
#figure(
|
||
image("../Pictures/LocalNetworkUsageAlert.jpeg", height: 95%),
|
||
kind: image,
|
||
caption: "Monit z prośbą o dostęp do sieci lokalnej",
|
||
)
|
||
|
||
== Napotkane wyzwania implementacyjne i rozwiązania
|
||
|
||
W czasie implementacji opisywanej aplikacji natknąłem się na problemy, które były związane z poszczególnymi częściami synchronizacji tekstu. Pierwszym z nich jest zachowanie frameworka Multipeer Connectivity, gdzie nasłuchiwanie na dostępnych użytkowników za pomocą `MCNearbyServiceBrowser` wykrywa także samego siebie jako jednego z dostępnych klientów. Skutkowało to wysyłaniem zmian przez urządzenie do samego siebie oraz otrzymywanie zduplikowanych kopii notatek z innych urządzeń. By temu zapobiec, w metodzie obsługującej wykrywanie dostępnych użytkowników - widocznej w programie 3.7 - zaimplementowałem filtr, który ignoruje użytkowników o takiej samej nazwie użytkownika.
|
||
|
||
Następnym problemem związanym z Multipeer Connectivity jest jego ogólna niestabilność. W sytuacjach, gdzie połączenie staje się niestabilne - oddalenie się od siebie użytkowników, gdy do komunikacji jest wykorzystywany Bluetooth; przełączanie się między sieciami Wi-Fi - otrzymywane zdarzenia nie są deterministyczne. Czasem aplikacja otrzymywała na przemian informacje o rozłączeniu i ponownym połączeniu się z zaproszonymi klientami, czasem nigdy nie otrzymywała informacji o tym, że klient się rozłączył. Podobne problemy zostały zauważone w momencie wyjścia z aplikacji - wielokrotnie aplikacja traciła połączenie z innymi klientami, ale metody, które powinny zostać z tego powodu wywołane, czasami nie były wykonywane.
|
||
|
||
Ostatnim, najcięższym problemem jest aktualizacja pozycji kursora w edytorze tekstu. W momencie nanoszenia zmian należy rozważyć, czy został wstawiony lub usunięty tekst z części notatki, która znajduje się na wcześniejszej pozycji względem kursora każdego z użytkowników. Jeśli tak, to poprawnym zachowaniem byłoby przeniesienie odpowiednio kursora tak, by żaden z klientów nie spotkał się z sytuacją, gdzie kursor zmienia swoje położenie bez wyraźnej akcji użytkownika. Jest to problematyczne w aktualnej implementacji z dwóch powodów. Pierwszym problemem jest algorytm nanoszenia zmian - ze względu na to, że sposób w jaki ten proces wykonujemy polega na całkowitej podmianie istniejącego tekstu na nowy, powinno się przed jego wykonaniem ustalić wcześniej wspomniane istnienie zmian tekstu na pozycji wcześniejszej od kursora użytkownika. Przez to, że nie wykorzystywane są tutaj struktury CRDT, które mają bardzo dokładne informacje o nanoszonych zmianach, musimy polegać na ręcznej analizie obu ciągów tekstowych. Takie przeliczanie jest też problematyczne w przypadku obsługi wszystkich wspieranych przez system alfabetów. Następnym problemem jest niestabilny interfejs do manipulacji pozycją kursora w edytorze tekstu dostarczanym przez SwiftUI. Proces aktualizacji polega najpierw na wyliczeniu punktu przesunięcia kursora, następnie zamianę tekstu w edytorze na zaktualizowaną wersję i finalnie podmianę pozycji kursora. Testy manualne aplikacji wykazały, że kolejność nanoszenia dwóch ostatnich zmian an interfejs graficzny użytkownika przez SwiftUI jest niedeterministyczne. Zdarzały się sytuacje, gdzie pozycja kursora była aktualizowana przed naniesieniem nowej wersji tekstu. Bardzo często to się zdarzało w przypadku, gdy zawartość tekstowa była wielkości przynajmniej 1000 znaków. Najstabilniejszym rozwiązaniem, które nie wymagało implementacji struktur CRDT oraz implementacji kursora od zera z wykorzystaniem starszego frameworka - UIKit - okazało się pozostawienie domyślnego zachowania podczas zewnętrznej aktualizacji tekstu w edytorze. Niestety nadal można zaobserwować błędy z tym związane, ale nie są one tak częste jak w przypadku, gdy tym kursorem aplikacja próbowała dodatkowo manipulować obok istniejącego mechanizmu dostarczanego przez SwiftUI, którego nie da się wyłączyć.
|
||
|
||
== Ograniczenia środowisk iOS/iPadOS
|
||
|
||
Ze względu na to, że aplikacja została napisana w pełni z wykorzystaniem natywnych technologii - Swift, SwiftUI, Combine, Multipeer Connectivity - projekt aplikacji jest niemożliwy do zbudowania bez posiadania komputera z najnowszą wersją systemu macOS oraz środowiska programistycznego Xcode. Kolejnym problemem jest obowiązek posiadania konta Apple Developer, który wymaga wyrażenia zgody na regulamin użytkowania oprogramowania dostarczanego przez firmę Apple do rozwoju aplikacji na systemy operacyjne iOS i iPadOS. Wszystkie wspomniane wymogi sprawiają, że kontrybucja do kodu źródłowego aplikacji jak i jej kompilacja we własnym zakresie jest bardzo utrudniona.
|
||
|
||
Następnym problemem jest interfejs frameworku Multipeer Connectivity. Opiera się on na przekazywaniu obustronnie specjalnych obiektów oraz narzuca konkretne sposoby wymiany danych między instancjami aplikacji. Sprawia to, że implementacja, bez tworzenia dodatkowych warstw abstrakcji, nie jest możliwa do rozszerzenia o wsparcie innych systemów operacyjnych. Rozważaną alternatywą było użycie frameworku Network, który opiera się na przesyłaniu ramek TCP, ale to znacznie zwiększało złożoność całej implementacji.
|