danabra.mov
forked from
samuel.fm/statusphere-react
the statusphere demo reworked into a vite/react app in a monorepo
A few tightening edits
+22
-38
TUTORIAL.md
+22
-38
TUTORIAL.md
···
119
119
120
120
## Step 3. Fetching the user's profile
121
121
122
-
Why don't we learn something about our user? Let's start by getting the [Agent](#todo) object. The [Agent](#todo) is the client to the user's `at://` repo server.
123
-
124
-
```typescript
125
-
/** src/routes.ts **/
126
-
async function getSessionAgent(
127
-
req: IncomingMessage,
128
-
res: ServerResponse<IncomingMessage>,
129
-
ctx: AppContext
130
-
) {
131
-
// Fetch the session from their cookie
132
-
const session = await getIronSession(req, res)
133
-
if (!session.did) return null
134
-
135
-
// "Restore" the agent for the user
136
-
try {
137
-
return await ctx.oauthClient.restore(session.did)
138
-
} catch(err) {
139
-
ctx.logger.warn({ err }, 'oauth restore failed')
140
-
await session.destroy()
141
-
return null
142
-
}
143
-
}
144
-
```
145
-
146
-
Users publish JSON records on their `at://` repos. In [Bluesky](https://bsky.app), they publish a "profile" record which looks like this:
122
+
Why don't we learn something about our user? In [Bluesky](https://bsky.app), users publish a "profile" record which looks like this:
147
123
148
124
```typescript
149
125
interface ProfileRecord {
···
156
132
}
157
133
```
158
134
159
-
We're going to use the [Agent](#todo) to fetch this record to include in our app.
135
+
You can examine this record directly using [atproto-browser.vercel.app](https://atproto-browser.vercel.app). For instance, [this is the profile record for @bsky.app](https://atproto-browser.vercel.app/at?u=at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.actor.profile/self).
136
+
137
+
We're going to use the [Agent](#todo) associated with the user's OAuth session to fetch this record.
160
138
161
139
```typescript
162
140
await agent.getRecord({
···
168
146
169
147
When asking for a record, we provide three pieces of information.
170
148
171
-
- The [DID](#todo) which identifies the user,
172
-
- The collection name, and
173
-
- The record key
149
+
- **repo** The [DID](#todo) which identifies the user,
150
+
- **collection** The collection name, and
151
+
- **rkey** The record key
174
152
175
153
We'll explain the collection name shortly. Record keys are strings with [some limitations](https://atproto.com/specs/record-key#record-key-syntax) and a couple of common patterns. The `"self"` pattern is used when a collection is expected to only contain one record which describes the user.
176
154
···
194
172
const { data: profileRecord } = await agent.getRecord({
195
173
repo: agent.accountDid, // our user's repo
196
174
collection: 'app.bsky.actor.profile', // the bluesky profile record type
197
-
rkey: 'self', // the record's name
175
+
rkey: 'self', // the record's key
198
176
})
199
177
200
178
// Serve the logged-in view
···
206
184
```
207
185
208
186
With that data, we can give a nice personalized welcome banner for our user:
187
+
188
+
209
189
210
190
```html
211
191
<!-- pages/home.ts -->
···
228
208
</div>`}
229
209
</div>
230
210
```
231
-
232
-
233
-
234
-
You can examine this record directly using [atproto-browser.vercel.app](https://atproto-browser.vercel.app). For instance, [this is the profile record for @bsky.app](https://atproto-browser.vercel.app/at?u=at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.actor.profile/self).
235
211
236
212
## Step 4. Reading & writing records
237
213
···
325
301
326
302
## Step 5. Creating a custom "status" schema
327
303
328
-
The collections are typed, meaning that they have a defined schema. The `app.bsky.actor.profile` type definition [can be found here](https://github.com/bluesky-social/atproto/blob/main/lexicons/app/bsky/actor/profile.json).
304
+
Repo collections are typed, meaning that they have a defined schema. The `app.bsky.actor.profile` type definition [can be found here](https://github.com/bluesky-social/atproto/blob/main/lexicons/app/bsky/actor/profile.json).
329
305
330
306
Anybody can create a new schema using the [Lexicon](#todo) language, which is very similar to [JSON-Schema](#todo). The schemas use [reverse-DNS IDs](#todo) which indicate ownership, but for this demo app we're going to use `com.example` which is safe for non-production software.
331
307
···
511
487
512
488
513
489
514
-
Why read from the event log? Because there are other apps in the network that will write the records we're interested in. By subscribing to the event log, we ensure that we catch all the data we're interested in -- including data published by other apps.
490
+
Applications write to the repo. The write events are then emitted on the firehose where they're caught by the apps and ingested into their databases.
491
+
492
+
Why sync from the event log like this? Because there are other apps in the network that will write the records we're interested in. By subscribing to the event log, we ensure that we catch all the data we're interested in — including data published by other apps!
515
493
516
494
## Step 7. Listing the latest statuses
517
495
···
567
545
568
546
## Step 8. Optimistic updates
569
547
570
-
As a final optimization, let's introduce "optimistic updates." Remember the information flow loop with the repo write and the event log? Since we're updating our users' repos locally, we can short-circuit that flow to our own database:
548
+
As a final optimization, let's introduce "optimistic updates."
549
+
550
+
Remember the information flow loop with the repo write and the event log?
551
+
552
+
553
+
554
+
Since we're updating our users' repos locally, we can short-circuit that flow to our own database:
571
555
572
556
573
557
···
633
617
- Design the [Lexicon](#) schemas for the records you'll publish into the Atmosphere.
634
618
- Create a database for aggregating the records into useful views.
635
619
- Build your application to write the records on your users' repos.
636
-
- Listen to the firehose to hydrate your aggregated database.
620
+
- Listen to the firehose to aggregate data across the network.
637
621
638
622
Remember this flow of information throughout:
639
623