commit 38ad0a29f2cc030ff3b60a71edc2f6dee6ba4f44 · cduck.me/statusphere-example-app-fork

+22 -38
TUTORIAL.md
···

       119
       119
        
       

     

       120
       120
        
       ## Step 3. Fetching the user's profile

     

       121
       121
        
       

     

       122
       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
       123
       -
       

     

       124
       124
       -
       ```typescript

     

       125
       125
       -
       /** src/routes.ts **/

     

       126
       126
       -
       async function getSessionAgent(

     

       127
       127
       -
         req: IncomingMessage,

     

       128
       128
       -
         res: ServerResponse<IncomingMessage>,

     

       129
       129
       -
         ctx: AppContext

     

       130
       130
       -
       ) {

     

       131
       131
       -
         // Fetch the session from their cookie

     

       132
       132
       -
         const session = await getIronSession(req, res)

     

       133
       133
       -
         if (!session.did) return null

     

       134
       134
       -
       

     

       135
       135
       -
         // "Restore" the agent for the user

     

       136
       136
       -
         try {

     

       137
       137
       -
           return await ctx.oauthClient.restore(session.did)

     

       138
       138
       -
         } catch(err) {

     

       139
       139
       -
           ctx.logger.warn({ err }, 'oauth restore failed')

     

       140
       140
       -
           await session.destroy()

     

       141
       141
       -
           return null

     

       142
       142
       -
         }

     

       143
       143
       -
       }

     

       144
       144
       -
       ```

     

       145
       145
       -
       

     

       146
       146
       -
       Users publish JSON records on their `at://` repos. In [Bluesky](https://bsky.app), they publish a "profile" record which looks like this:

     

       122
       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
       159
       -
       We're going to use the [Agent](#todo) to fetch this record to include in our app.

     

       135
       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
       136
       +
       

     

       137
       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
       171
       -
       - The [DID](#todo) which identifies the user,

     

       172
       172
       -
       - The collection name, and

     

       173
       173
       -
       - The record key

     

       149
       149
       +
       - **repo** The [DID](#todo) which identifies the user,

     

       150
       150
       +
       - **collection** The collection name, and

     

       151
       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
       197
       -
             rkey: 'self',                         // the record's name

     

       175
       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
       187
       +
       

     

       188
       188
       +
       ![A screenshot of the banner image](./docs/app-banner.png)

     

       209
       189
        
       

     

       210
       190
        
       ```html

     

       211
       191
        
       <!-- pages/home.ts -->

     
···

       228
       208
        
             </div>`}

     

       229
       209
        
       </div>

     

       230
       210
        
       ```

     

       231
       231
       -
       

     

       232
       232
       -
       ![A screenshot of the banner image](./docs/app-banner.png)

     

       233
       233
       -
       

     

       234
       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
       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
       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
        
       ![A diagram of the flow of information](./docs/diagram-info-flow.png)

     

       513
       489
        
       

     

       514
       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
       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
       491
       +
       

     

       492
       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 &mdash; 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
       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
       548
       +
       As a final optimization, let's introduce "optimistic updates."

     

       549
       549
       +
       

     

       550
       550
       +
       Remember the information flow loop with the repo write and the event log?

     

       551
       551
       +
       

     

       552
       552
       +
       ![A diagram of the flow of information](./docs/diagram-info-flow.png)

     

       553
       553
       +
       

     

       554
       554
       +
       Since we're updating our users' repos locally, we can short-circuit that flow to our own database:

     

       571
       555
        
       

     

       572
       556
        
       ![A diagram illustrating optimistic updates](./docs/diagram-optimistic-update.png)

     

       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
       636
       -
       - Listen to the firehose to hydrate your aggregated database.

     

       620
       620
       +
       - Listen to the firehose to aggregate data across the network.

     

       637
       621
        
       

     

       638
       622
        
       Remember this flow of information throughout:

     

       639
       623