Skip to content

Commit bc40e71

Browse files
author
Patryk Lesiewicz
authored
PREINSTALL and POSTINSTALL changes (#359)
1 parent 2701eae commit bc40e71

File tree

2 files changed

+59
-51
lines changed

2 files changed

+59
-51
lines changed

‎firestore-counter/POSTINSTALL.md

Lines changed: 45 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,28 @@ Before you can use this extension, you'll need to update your security rules, se
44

55
#### Update security rules
66

7-
Update your Cloud Firestore security rules to allow reads and writes to the `_counter_shards_` subcollection where you want the extension to count, for example:
7+
Update your Cloud Firestore security rules to allow lookups and writes to the `_counter_shards_` subcollection where you want the extension to count. For example, to allow clients to increment the `visits` field on any document in the `pages` collection, you can write rules like this:
88

99
```
1010
match /databases/{database}/documents/pages/{page} {
11-
// Allow to increment only 'visits' field and only by 1.
11+
// Allow to increment only the 'visits' field and only by 1.
1212
match /_counter_shards_/{shardId} {
13-
allow read;
14-
allow create: if request.resource.data.keys().size() == 1 &&
15-
request.resource.data.visits == 1;
16-
allow update: if request.resource.data.keys().size() == 1 &&
17-
request.resource.data.visits == resource.data.visits + 1;
18-
allow delete: if false;
13+
allow get;
14+
allow write: if request.resource.data.keys() == ["visits"]
15+
&& (resource == null || request.resource.data.visits ==
16+
resource.data.visits + 1);
1917
}
2018
}
2119
```
2220

2321
#### Set up a scheduled function
2422

25-
Set up a [scheduled function](https://firebase.google.com/docs/functions/schedule-functions) to call `${function:controller.url}` every minute.
23+
Review the [scheduled function documentation](https://firebase.google.com/docs/functions/schedule-functions) to set up a call to `${function:controller.url}` every minute. You may need to enable some APIs in your Firebase project to use scheduled functions.
2624

27-
For example, to set up a scheduled function, you can run the following [`gcloud`](https://cloud.google.com/sdk/gcloud/) command:
25+
As an example, to set up a scheduled function, you can run the following [`gcloud`](https://cloud.google.com/sdk/gcloud/) commands:
2826

2927
```
28+
gcloud services enable cloudscheduler.googleapis.com
3029
gcloud scheduler jobs create http firestore-sharded-counter-controller --schedule="* * * * *" --uri=${function:controller.url} --project=${param:PROJECT_ID}
3130
```
3231

@@ -36,46 +35,45 @@ gcloud scheduler jobs create http firestore-sharded-counter-controller --schedul
3635

3736
Note: You might get a "Permission denied" error for the source repository. If you do, locate the **Sign in** button on the error page, then sign in to access to the repo.
3837

39-
1. Use the Counter SDK library in your code:
40-
41-
```html
42-
<html>
43-
<head>
44-
<script src="https://www.gstatic.com/firebasejs/[version]/firebase-app.js"></script>
45-
<script src="https://www.gstatic.com/firebasejs/[version]/firebase-firestore.js"></script>
46-
<script src="sharded-counter.js"></script>
47-
</head>
48-
<body>
49-
<script>
50-
// Initialize Firebase.
51-
var firebaseConfig = { projectId: "${PROJECT_ID}" };
52-
firebase.initializeApp(firebaseConfig);
53-
var db = firebase.firestore();
54-
55-
// Initialize the sharded counter.
56-
var views = new sharded.Counter(db.doc("pages/hello-world"), "stats.views");
57-
58-
// Increment by 3 the field "stats.views" of the document: ${param:MOD_METADATA_DOC}.
59-
// (use your desired increment amount)
60-
views.incrementBy(3);
61-
62-
// Listen to locally consistent values.
63-
views.onSnapshot((snap) => {
64-
console.log("Locally consistent view of visits: " + snap.data());
65-
});
66-
67-
// Alternatively, if you don't mind counter delays, you can listen to the document directly.
68-
db.doc("pages/hello-world").onSnapshot((snap) => {
69-
console.log("Eventually consistent view of visits: " + snap.get("stats.views"));
70-
})
71-
</script>
72-
</body>
73-
</html>
74-
```
38+
1. Use the Counter SDK library in your code to increment counters. The code snippet below shows an example of how to use the library. For more comprehensive API documentation, refer to the [source code](https://dev-partners.googlesource.com/samples/firebase/mods/+/master/firestore-counter/clients/web/src/index.ts).
39+
40+
```html
41+
<html>
42+
<head>
43+
<script src="https://www.gstatic.com/firebasejs/[version]/firebase-app.js"></script>
44+
<script src="https://www.gstatic.com/firebasejs/[version]/firebase-firestore.js"></script>
45+
<script src="sharded-counter.js"></script>
46+
</head>
47+
<body>
48+
<script>
49+
// Initialize Firebase.
50+
var firebaseConfig = { projectId: "${PROJECT_ID}" };
51+
firebase.initializeApp(firebaseConfig);
52+
var db = firebase.firestore();
53+
54+
// Initialize the sharded counter.
55+
var visits = new sharded.Counter(db.doc("pages/hello-world"), "visits");
56+
57+
// Increment the field "visits" of the document "pages/hello-world".
58+
visits.incrementBy(1);
59+
60+
// Listen to locally consistent values.
61+
visits.onSnapshot((snap) => {
62+
console.log("Locally consistent view of visits: " + snap.data());
63+
});
64+
65+
// Alternatively, if you don't mind counter delays, you can listen to the document directly.
66+
db.doc("pages/hello-world").onSnapshot((snap) => {
67+
console.log("Eventually consistent view of visits: " + snap.get("visits"));
68+
});
69+
</script>
70+
</body>
71+
</html>
72+
```
7573

7674
### Using the extension
7775

78-
After you complete the post-installation configuration above, your extension will create subcollections in all the documents that your app uses as counters. The extension will use these subcollections to help track the counter in a scalable way.
76+
After you complete the post-installation configuration above, your extension will create subcollections in all the documents that your app uses as counters. The client SDK will write to these subcollections to distribute the write load, and the scheduled function you deployed will sum the subcollections' values into the single `visits` field (or whichever field you configured).
7977

8078
### Monitoring
8179

‎firestore-counter/PREINSTALL.md

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,26 @@
11
Use this extension to add a highly scalable counter service to your app. This is ideal for applications that count viral actions or any very high-velocity action such as views, likes, or shares.
22

3-
In your app, you specify a Cloud Firestore document path and increment a field value by any amount you choose. The extension then creates a subcollection in that document to help track the counter in a scalable way.
3+
Since Cloud Firestore has a limit of one sustained write per second, per document, this extension instead shards your writes across documents in a `_counter_shards_` subcollection. Each client only increments their own unique shard while the background workers (provided by this extension) monitor and aggregate these shards into a main document.
4+
5+
Here are some features of this extension:
6+
- Scales from 0 updates per second to at least 10,000 per second.
7+
- Supports an arbitrary number of counters in your app.
8+
- Works offline and provides latency compensation for the main counter.
9+
10+
Note that this extension is currently fully resourced for use with JavaScript apps (we provide the required [JS SDK](https://dev-partners.googlesource.com/samples/firebase/mods/+/master/firestore-sharded-counter/clients/web/src/index.ts)). You can, however, use this extension on other platforms if you'd like to develop your own API based on the provided JS SDK.
411

5-
Note that this extension is for use with the JavaScript apps and requires the Firebase JavaScript SDK.
612

713
#### Additional setup
814

915
Before installing this extension, make sure that you've [set up a Cloud Firestore database](https://firebase.google.com/docs/firestore/quickstart) in your Firebase project.
1016

11-
After installation, you'll need to update your database security rules and set up a [scheduled function](https://firebase.google.com/docs/functions/schedule-functions) to regularly call one of the functions created by this extension. Detailed information for these post-installation tasks are provided after you install this extension.
17+
After installing this extension, you'll need to:
18+
- Update your [database security rules](https://firebase.google.com/docs/rules).
19+
- Set up a [scheduled function](https://firebase.google.com/docs/functions/schedule-functions) to regularly call the controller function, which is created by this extension and monitors the extension's workload.
20+
- Install the provided [Counter SDK](https://dev-partners.googlesource.com/samples/firebase/mods/+/master/firestore-sharded-counter/clients/web/src/index.ts) in your app. You can then use this library in your code to specify your document path and increment values.
21+
22+
Detailed information for these post-installation tasks are provided after you install this extension.
1223

13-
This extension provides a Counter SDK that you need to install in your app. You can then use this library in your code to specify your document path and increment values. Detailed instructions to install this SDK and use it are provided after you install this extension.
1424

1525
#### Billing
1626

0 commit comments

Comments
 (0)