Skip to content

Commit 9575409

Browse files
cbaker6TomWFox
cbaker6
and
TomWFox
authored
LiveQuery Support (#45)
* wip * WIP * Finished initial version of LiveQuerySocket * add websocket metrics * Able to connect to liveQuery server. * Comment out LiveQuery test case * Remove metrics for watchOS * Update to how to create LiveQuery instance. Updated socket state machine * Delegate authentication challenges to the dev, they handle their own cert pinning and auth. If no delegate, use default iOS * Migrate all parse network calls to a dedicated singleton. Adds authentication challenge to parse calls * LiveQuery authentication process: 1) check dev provided delegate method, 2) check parse auth provide by dev, 3) use default iOS * Simplify calls to parse URLSession * fix playground project * Let url session be lazily initialized * Documentation * more docs * Allow multiple LiveQuery connections. * Enable subscribe/unsubscribe * Test the rest of split array * Clean up * Update socket * Tie together Query and Subscription * Align terminology with JS SDK * Working version and docs * remove extra prints * Fix unsubscribe, align syntax closer to JS SDK, add redirect and update query * Add clientId and installationId to verification of messages between client and server. * SDK - Use .POST instead of .GET for user login * Add LiveQuery "fields" example. Initial shot at adding LiveQuery to readme. * Update README.md * Update README.md * All LiveQuery clients have their own thread. Added reconnection logic * Test LiveQuery state machine * Test initializers and default client * Test delegates * Add test cases * Disable flaky test for now * codecov patch auto * Comment out flakey test so it doesn't run in SPM * Add another test, lower codecov patch. * Fix flakey test * Improve test * put larger dispatch window on test * Remove test that's iffy because of threading issue. * Fix iffy test * docs * more docs * More tests * Fix try init in tests. Broke them on accident. * Apply suggestions from code review Co-authored-by: Tom Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Tom Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Tom Fox <[email protected]> Co-authored-by: Tom Fox <[email protected]>
1 parent 2f77fd6 commit 9575409

38 files changed

+2956
-161
lines changed

‎.codecov.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ coverage:
55
status:
66
patch:
77
default:
8-
target: 73
8+
target: 69
99
changes: false
1010
project:
1111
default:

‎.swiftlint.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
disabled_rules:
2+
- file_length
3+
- cyclomatic_complexity
4+
- function_body_length
5+
- type_body_length
6+
- inclusive_language

‎ParseSwift.playground/Pages/11 - LiveQuery.xcplaygroundpage/Contents.swift

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
//: [Previous](@previous)
2+
3+
import PlaygroundSupport
4+
import Foundation
5+
import ParseSwift
6+
PlaygroundPage.current.needsIndefiniteExecution = true
7+
8+
initializeParse()
9+
10+
//: Create your own ValueTyped ParseObject
11+
struct GameScore: ParseObject {
12+
//: These are required for any Object
13+
var objectId: String?
14+
var createdAt: Date?
15+
var updatedAt: Date?
16+
var ACL: ParseACL?
17+
18+
//: Your own properties
19+
var score: Int = 0
20+
var location: ParseGeoPoint?
21+
var name: String?
22+
23+
//custom initializer
24+
init(name: String, score: Int) {
25+
self.name = name
26+
self.score = score
27+
}
28+
}
29+
30+
//: Be sure you have LiveQuery enabled on your server.
31+
32+
//: Create a query just as you normally would.
33+
var query = GameScore.query("score" > 9)
34+
35+
//: This is how you subscribe your created query
36+
let subscription = query.subscribe!
37+
38+
//: This is how you receive notifications about the success
39+
//: of your subscription.
40+
subscription.handleSubscribe { subscribedQuery, isNew in
41+
42+
//: You can check this subscription is for this query
43+
if isNew {
44+
print("Successfully subscribed to new query \(subscribedQuery)")
45+
} else {
46+
print("Successfully updated subscription to new query \(subscribedQuery)")
47+
}
48+
}
49+
50+
//: This is how you register to receive notificaitons of events related to your LiveQuery.
51+
subscription.handleEvent { _, event in
52+
switch event {
53+
54+
case .entered(let object):
55+
print("Entered: \(object)")
56+
case .left(let object):
57+
print("Left: \(object)")
58+
case .created(let object):
59+
print("Created: \(object)")
60+
case .updated(let object):
61+
print("Updated: \(object)")
62+
case .deleted(let object):
63+
print("Deleted: \(object)")
64+
}
65+
}
66+
67+
//: Now go to your dashboard, go to the GameScore table and add, update or remove rows.
68+
//: You should receive notifications for each.
69+
70+
//: This is how you register to receive notificaitons about being unsubscribed.
71+
subscription.handleUnsubscribe { query in
72+
print("Unsubscribed from \(query)")
73+
}
74+
75+
//: To unsubscribe from your query.
76+
do {
77+
try query.unsubscribe()
78+
} catch {
79+
print(error)
80+
}
81+
82+
//: Create a new query.
83+
var query2 = GameScore.query("score" > 50)
84+
85+
//: Select the fields you are interested in receiving.
86+
query2.fields("score")
87+
88+
//: Subscribe to your new query.
89+
let subscription2 = query2.subscribe!
90+
91+
//: As before, setup your subscription and event handlers.
92+
subscription2.handleSubscribe { subscribedQuery, isNew in
93+
94+
//: You can check this subscription is for this query.
95+
if isNew {
96+
print("Successfully subscribed to new query \(subscribedQuery)")
97+
} else {
98+
print("Successfully updated subscription to new query \(subscribedQuery)")
99+
}
100+
}
101+
102+
subscription2.handleEvent { _, event in
103+
switch event {
104+
105+
case .entered(let object):
106+
print("Entered: \(object)")
107+
case .left(let object):
108+
print("Left: \(object)")
109+
case .created(let object):
110+
print("Created: \(object)")
111+
case .updated(let object):
112+
print("Updated: \(object)")
113+
case .deleted(let object):
114+
print("Deleted: \(object)")
115+
}
116+
}
117+
118+
//: Now go to your dashboard, go to the GameScore table and add, update or remove rows.
119+
//: You should receive notifications for each, but only with your fields information.
120+
121+
//: This is how you register to receive notificaitons about being unsubscribed.
122+
subscription2.handleUnsubscribe { query in
123+
print("Unsubscribed from \(query)")
124+
}
125+
126+
//: To unsubscribe from your query.
127+
do {
128+
try query2.unsubscribe()
129+
} catch {
130+
print(error)
131+
}
132+
133+
PlaygroundPage.current.finishExecution()
134+
//: [Next](@next)

‎ParseSwift.playground/contents.xcplayground

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,6 @@
1111
<page name='8 - Pointers'/>
1212
<page name='9 - Files'/>
1313
<page name='10 - Cloud Code'/>
14+
<page name='11 - LiveQuery'/>
1415
</pages>
1516
</playground>

‎ParseSwift.xcodeproj/project.pbxproj

Lines changed: 135 additions & 1 deletion
Large diffs are not rendered by default.

‎README.md

Lines changed: 87 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
</p>
2727
<br>
2828

29-
For more information about the Parse Platform and its features, see the public [documentation][docs].
29+
For more information about the Parse Platform and its features, see the public [documentation][docs]. The ParseSwift SDK is not a port of the [Parse-SDK-iOS-OSX SDK](https://github.com/parse-community/Parse-SDK-iOS-OSX) and though some of it may feel familiar, it is not backwards compatible and is designed with a new philosophy. For more details visit the [api documentation](http://parseplatform.org/Parse-Swift/api/).
3030

3131
## Installation
3232

@@ -66,12 +66,95 @@ github "parse-community/Parse-Swift" "main"
6666
```
6767
Run `carthage update`, and you should now have the latest version of ParseSwift SDK in your Carthage folder.
6868
69-
## iOS Usage Guide
69+
## Usage Guide
7070
7171
After installing ParseSwift, to use it first `import ParseSwift` in your AppDelegate.swift and then add the following code in your `application:didFinishLaunchingWithOptions:` method:
7272
```swift
73-
ParseSwift.initialize(applicationId: "xxxxxxxxxx", clientKey: "xxxxxxxxxx", serverURL: URL(string: "https://example.com")!)
73+
ParseSwift.initialize(applicationId: "xxxxxxxxxx", clientKey: "xxxxxxxxxx", serverURL: URL(string: "https://example.com")!, liveQueryServerURL: URL(string: "https://example.com")!, authentication: ((URLAuthenticationChallenge,
74+
(URLSession.AuthChallengeDisposition,
75+
URLCredential?) -> Void) -> Void))
7476
```
7577
Please checkout the [Swift Playground](https://github.com/parse-community/Parse-Swift/tree/main/ParseSwift.playground) for more usage information.
7678

77-
[docs]: http://docs.parseplatform.org/ios/guide/
79+
[docs]: https://docs.parseplatform.org
80+
81+
82+
## LiveQuery
83+
`Query` is one of the key concepts on the Parse Platform. It allows you to retrieve `ParseObject`s by specifying some conditions, making it easy to build apps such as a dashboard, a todo list or even some strategy games. However, `Query` is based on a pull model, which is not suitable for apps that need real-time support.
84+
85+
Suppose you are building an app that allows multiple users to edit the same file at the same time. `Query` would not be an ideal tool since you can not know when to query from the server to get the updates.
86+
87+
To solve this problem, we introduce Parse LiveQuery. This tool allows you to subscribe to a `Query` you are interested in. Once subscribed, the server will notify clients whenever a `ParseObject` that matches the `Query` is created or updated, in real-time.
88+
89+
### Setup Server
90+
91+
Parse LiveQuery contains two parts, the LiveQuery server and the LiveQuery clients (this SDK). In order to use live queries, you need to at least setup the server.
92+
93+
The easiest way to setup the LiveQuery server is to make it run with the [Open Source Parse Server](https://github.com/ParsePlatform/parse-server/wiki/Parse-LiveQuery#server-setup).
94+
95+
96+
### Use Client
97+
98+
The LiveQuery client interface is based around the concept of `Subscription`s. You can register any `Query` for live updates from the associated live query server, by simply calling `subscribe()` on a query:
99+
```swift
100+
let myQuery = Message.query("from" == "parse")
101+
guard let subscription = myQuery.subscribe else {
102+
"Error subscribing..."
103+
return
104+
}
105+
```
106+
107+
Where `Message` is a ParseObject.
108+
109+
Once you've subscribed to a query, you can `handle` events on them, like so:
110+
```swift
111+
subscription.handleSubscribe { subscribedQuery, isNew in
112+
113+
//Handle the subscription however you like.
114+
if isNew {
115+
print("Successfully subscribed to new query \(subscribedQuery)")
116+
} else {
117+
print("Successfully updated subscription to new query \(subscribedQuery)")
118+
}
119+
}
120+
```
121+
122+
You can handle any event listed in the LiveQuery [spec](https://github.com/parse-community/parse-server/wiki/Parse-LiveQuery-Protocol-Specification#event-message):
123+
```swift
124+
subscription.handleEvent { _, event in
125+
// Called whenever an object was created
126+
switch event {
127+
128+
case .entered(let object):
129+
print("Entered: \(object)")
130+
case .left(let object):
131+
print("Left: \(object)")
132+
case .created(let object):
133+
print("Created: \(object)")
134+
case .updated(let object):
135+
print("Updated: \(object)")
136+
case .deleted(let object):
137+
print("Deleted: \(object)")
138+
}
139+
}
140+
```
141+
142+
Similiarly, you can unsubscribe and register to be notified when it occurs:
143+
```swift
144+
subscription.handleUnsubscribe { query in
145+
print("Unsubscribed from \(query)")
146+
}
147+
148+
//: To unsubscribe from your query.
149+
do {
150+
try query.unsubscribe()
151+
} catch {
152+
print(error)
153+
}
154+
```
155+
156+
Handling errors is and other events is similar, take a look at the `Subscription` class for more information.
157+
158+
### Advanced Usage
159+
160+
You are not limited to a single Live Query Client - you can create multiple instances of `ParseLiveQuery`, use certificate authentication and pinning, receive metrics about each client connection, connect to individual server URLs, and more.

‎Sources/ParseSwift/API/API+Commands.swift

Lines changed: 13 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@ import FoundationNetworking
1313

1414
// MARK: API.Command
1515
internal extension API {
16-
// swiftlint:disable:next type_body_length
1716
struct Command<T, U>: Encodable where T: ParseType {
1817
typealias ReturnType = U // swiftlint:disable:this nesting
1918
let method: API.Method
@@ -59,17 +58,10 @@ internal extension API {
5958

6059
case .success(let urlRequest):
6160
if method == .POST || method == .PUT {
62-
if !ParseConfiguration.isTestingSDK {
63-
let delegate = ParseURLSessionDelegate(callbackQueue: nil,
64-
uploadProgress: uploadProgress,
65-
stream: stream)
66-
let session = URLSession(configuration: .default,
67-
delegate: delegate,
68-
delegateQueue: nil)
69-
session.uploadTask(withStreamedRequest: urlRequest).resume()
70-
} else {
71-
URLSession.testing.uploadTask(withStreamedRequest: urlRequest).resume()
72-
}
61+
let task = URLSession.parse.uploadTask(withStreamedRequest: urlRequest)
62+
ParseConfiguration.sessionDelegate.uploadDelegates[task] = uploadProgress
63+
ParseConfiguration.sessionDelegate.streamDelegates[task] = stream
64+
task.resume()
7365
return
7466
}
7567
case .failure(let error):
@@ -118,7 +110,7 @@ internal extension API {
118110
childObjects: childObjects,
119111
childFiles: childFiles) {
120112
case .success(let urlRequest):
121-
URLSession.shared.dataTask(with: urlRequest, mapper: mapper) { result in
113+
URLSession.parse.dataTask(with: urlRequest, mapper: mapper) { result in
122114
switch result {
123115

124116
case .success(let decoded):
@@ -141,26 +133,17 @@ internal extension API {
141133
}
142134
} else {
143135
//ParseFiles are handled with a dedicated URLSession
144-
let session: URLSession!
145-
let delegate: URLSessionDelegate!
146136
if method == .POST || method == .PUT {
147137
switch self.prepareURLRequest(options: options,
148138
childObjects: childObjects,
149139
childFiles: childFiles) {
150140

151141
case .success(let urlRequest):
152-
if !ParseConfiguration.isTestingSDK {
153-
delegate = ParseURLSessionDelegate(callbackQueue: callbackQueue,
154-
uploadProgress: uploadProgress)
155-
session = URLSession(configuration: .default,
156-
delegate: delegate,
157-
delegateQueue: nil)
158-
} else {
159-
session = URLSession.testing
160-
}
161-
session.uploadTask(with: urlRequest,
142+
143+
URLSession.parse.uploadTask(with: urlRequest,
162144
from: uploadData,
163145
from: uploadFile,
146+
progress: uploadProgress,
164147
mapper: mapper) { result in
165148
switch result {
166149

@@ -184,22 +167,15 @@ internal extension API {
184167
}
185168
} else {
186169

187-
if !ParseConfiguration.isTestingSDK {
188-
delegate = ParseURLSessionDelegate(callbackQueue: callbackQueue,
189-
downloadProgress: downloadProgress)
190-
session = URLSession(configuration: .default,
191-
delegate: delegate,
192-
delegateQueue: nil)
193-
} else {
194-
session = URLSession.testing
195-
}
196170
if parseURL != nil {
197171
switch self.prepareURLRequest(options: options,
198172
childObjects: childObjects,
199173
childFiles: childFiles) {
200174

201175
case .success(let urlRequest):
202-
session.downloadTask(with: urlRequest, mapper: mapper) { result in
176+
URLSession.parse.downloadTask(with: urlRequest,
177+
progress: downloadProgress,
178+
mapper: mapper) { result in
203179
switch result {
204180

205181
case .success(let decoded):
@@ -222,7 +198,7 @@ internal extension API {
222198
}
223199
} else if let otherURL = self.otherURL {
224200
//Non-parse servers don't receive any parse dedicated request info
225-
session.downloadTask(with: otherURL, mapper: mapper) { result in
201+
URLSession.parse.downloadTask(with: otherURL, mapper: mapper) { result in
226202
switch result {
227203

228204
case .success(let decoded):
@@ -640,7 +616,7 @@ internal extension API {
640616

641617
switch self.prepareURLRequest(options: options) {
642618
case .success(let urlRequest):
643-
URLSession.shared.dataTask(with: urlRequest, mapper: mapper) { result in
619+
URLSession.parse.dataTask(with: urlRequest, mapper: mapper) { result in
644620
switch result {
645621

646622
case .success(let decoded):

0 commit comments

Comments
 (0)