Index of every page on this site: llms.txt
All skills
bluesky-social avatar

/lexification-server

@d9cdc54
by bluesky-socialbluesky-social/atproto9.7k stars
941
Run it yourself

Migrate a service package off the legacy server stack — `lex gen-server` codegen, a committed `src/lexicon/` tree, `server.<ns>.<method>()` route chains, `@atproto/api` inside service code — onto `@atproto/lex` and `@atproto/xrpc-server`. Use when asked to lexify, modernize, or migrate a server package; when a route file imports `Server` or `createServer` from `../lexicon/index.js`; when replacing `ids.*` constants, generated `isX()` guards, `server.xrpc.router`, or `QueryParams`/`OutputSchema` type imports; and when a package still runs `lex gen-server` in its `codegen:lex` script. For the calls a service makes *out* to other services, use lexification-client. For writing new routes on an already-migrated package, use xrpc-server.

  • 4 files
  • 25.4 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/bluesky-social/atproto/lexification-server

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesroutes.md

≈1.7k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Migrating route files

Read this for step 3: converting server.<ns>.<method>(…) registrations to server.add(schema, …), and moving parameter/output types off ../lexicon/types/….

For the target API in full — auth verifiers, rate limits, pipethrough, error classes — see the xrpc-server skill. This file covers only what the migration changes.

Registration

The namespace chain becomes a schema argument. Everything inside the config object is unchanged:

- server.app.bsky.feed.getAuthorFeed({
+ server.add(app.bsky.feed.getAuthorFeed, {
    auth: ctx.authVerifier.standardReadOrRoleOptional,
    handler: async ({ params, auth, req }) => { /* unchanged */ },
  })

The bare-handler form drops the wrapper object:

- server.com.atproto.identity.resolveHandle(async ({ req, params }) => {
+ server.add(com.atproto.identity.resolveHandle, async ({ params }) => {

The schema always comes from the generated tree, imported at the top of the file alongside Server:

import type { Server } from '@atproto/xrpc-server'
import { com } from '../../../../lexicons/index.js'

Migrated code overwhelmingly uses the object form. Preserve whichever form the file already had; there is no reason to convert between them during a migration.

encoding and literal widening

The form of the route — bare handler vs { handler } object — is not what decides this. What matters is whether the returned literal is still contextually typed by server.add(). Returning it directly from a handler that declares at least one parameter is, in both forms, so as const is unnecessary. Contextual typing is lost when the response is built into an intermediate variable first, or when the handler declares no parameters at all (async () => ({ … })); then encoding widens to string and the overload fails with TS2769: No overload matches this call.

// contextually typed — `as const` unnecessary in either form
server.add(app.bsky.graph.getRelationships, {
  handler: async ({ params }) => {
    return { encoding: 'application/json', body: { actor, relationships } }
  },
})

// also contextually typed; the `as const` here is redundant but harmless,
// and is what the real resolveHandle route still carries
server.add(com.atproto.identity.resolveHandle, async ({ params }) => {
  return { encoding: 'application/json' as const, body: { did } }
})

Many existing routes carry as const where it is not strictly needed; it is harmless, so leave it alone rather than churning call sites. Full rules live in the xrpc-server skill.

satisfies …$Output on the returned envelope also pins the literal and works in either form, but it is verbose and the repo does not use it. If a return needs an explicit contract, the one real precedent annotates the body:

body: { /* … */ } satisfies app.bsky.unspecced.getConfig.$OutputBody,

($Output is the whole { encoding, body } envelope; $OutputBody is just the body. Mixing them up produces a confusing excess-property error.)

Type-only references

- import { QueryParams } from '../../../../lexicon/types/app/bsky/feed/getAuthorFeed'
+ import { app } from '../../../../lexicons/index.js'
- type Params = QueryParams
+ type Params = app.bsky.feed.getAuthorFeed.$Params
Legacy generated type Accessor
QueryParams $Params
InputSchema $InputBody
HandlerInput $Input
OutputSchema $OutputBody
HandlerSuccess $Output
subscription message union $Message
record / main object .Main
sub-definitions their own name (.ReplyRef, .ViewRecord)

Because the namespace object carries both values and types, one import { app } from '../lexicons/index.js' replaces every per-method type import in the file. Use import type when the file needs only types.

$lxm in auth and proxy code

Method-id strings that used to come from ids:

- const aud = computeProxyTo(ctx, req, ids.AppBskyActorGetPreferences)
+ const aud = computeProxyTo(ctx, req, app.bsky.actor.getPreferences.$lxm)

Inside a handler where only the schema object is in scope, l.getMain(ns) reaches the underlying method definition (.output.schema, .$type) — used by pds's read-after-write helpers and bsky's data-plane record routes.

Subscriptions

Register the same way; the handler is an async generator and messages are built with $build:

server.add(
  com.atproto.sync.subscribeRepos,
  async function* ({
    params,
    signal,
  }): AsyncGenerator<com.atproto.sync.subscribeRepos.$Message> {
    yield com.atproto.sync.subscribeRepos.commit.$build({ seq, time, ...evt })
  },
)

signal is an AbortSignal on the subscription context — pass it to whatever produces events so client disconnects unwind the generator. See packages/pds/src/api/com/atproto/sync/subscribeRepos.ts.

Errors thrown by handlers

Nothing to do. InvalidRequestError, AuthRequiredError, ForbiddenError, InternalServerError, UpstreamFailureError, UpstreamTimeoutError, NotEnoughResourcesError, and MethodNotImplementedError already come from @atproto/xrpc-server in unmigrated packages — the legacy generated tree never re-exported them. Leave those imports alone.

What does change is errors the service catches from its own outbound calls — those move from @atproto/xrpc's XRPCError to XrpcError from @atproto/lex-client. XrpcError is abstract: catch and narrow it, never construct it. That half belongs to lexification-client.

Header maps

- import { HeadersMap } from '@atproto/xrpc'
+ import type { Headers as HeadersMap } from '@atproto/xrpc-server'

Aliased because Headers collides with the DOM global, and type-only because Headers is a type. The types are not identical: legacy HeadersMap was Record<string, string | undefined>, the new Headers is Record<string, string>. Code that relied on assigning undefined to clear a header needs the key omitted instead.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at d9cdc54. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago
disable-model-invocation
false

README badge

README badge for bluesky-social/atproto/lexification-server