diff --git a/README.md b/README.md index 39a0f6bc346..0fe2bdade63 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,93 @@ -# AT Protocol (Authenticated Transfer Protocol) +# AT Protocol Reference Implementation (TypeScript) -This is a working repository for the AT Protocol, aka the Authenticated Transfer Protocol. +Welcome friends! ---- +This repository contains Bluesky's reference implementation of AT Protocol, and of the `app.bsky` microblogging application service backend. -**⚠️ This is not production-ready software. This project is in active development ⚠️** +## What is in here? ---- +**TypeScript Packages:** -## ℹ️ About this project +| Package | Docs | NPM | +| ----------------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | +| `@atproto/api`: client library | [README](./packages/api/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/api)](https://www.npmjs.com/package/@atproto/api) | +| `@atproto/common-web`: shared code and helpers which can run in web browsers | [README](./packages/common-web/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/common-web)](https://www.npmjs.com/package/@atproto/common-web) | +| `@atproto/common`: shared code and helpers which doesn't work in web browsers | [README](./packages/common/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/common)](https://www.npmjs.com/package/@atproto/common) | +| `@atproto/crypto`: cryptographic signing and key serialization | [README](./packages/crypto/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/crypto)](https://www.npmjs.com/package/@atproto/crypto) | +| `@atproto/identity`: DID and handle resolution | [README](./packages/identity/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/identity)](https://www.npmjs.com/package/@atproto/identity) | +| `@atproto/lexicon`: schema definition language | [README](./packages/lexicon/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/lexicon)](https://www.npmjs.com/package/@atproto/lexicon) | +| `@atproto/repo`: data storage structure, including MST | [README](./packages/repo/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/repo)](https://www.npmjs.com/package/@atproto/repo) | +| `@atproto/syntax`: string parsers for identifiers | [README](./packages/syntax/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/syntax)](https://www.npmjs.com/package/@atproto/syntax) | +| `@atproto/xrpc`: client-side HTTP API helpers | [README](./packages/xrpc/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/xrpc)](https://www.npmjs.com/package/@atproto/xrpc) | +| `@atproto/xrpc-server`: server-side HTTP API helpers | [README](./packages/xrpc-server/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/xrpc-server)](https://www.npmjs.com/package/@atproto/xrpc-server) | -To learn more about atproto, see: +**TypeScript Services:** -- [Protocol Documentation](https://atproto.com/docs) - - [Overview Guide](https://atproto.com/guides/overview) 👈 Good place to start -- The [Blogpost on self-authenticating data structures](https://blueskyweb.xyz/blog/3-6-2022-a-self-authenticating-social-protocol) +- `pds`: "Personal Data Server", hosting repo content for atproto accounts. Most implementation code in `packages/pds`, with runtime wrapper in `services/pds`. See [bluesky-social/pds](https://github.com/bluesky-social/pds) for directions on self-hosting in the [federation sandbox network](https://atproto.com/blog/federation-developer-sandbox). +- `bsky`: AppView implementation of the `app.bsky.*` API endpoints. Running on main network at `api.bsky.app`. Most implementation code in `packages/bsky`, with runtime wrapper in `services/bsky`. -## Rules & Guidelines +**Lexicons:** for both the `com.atproto.*` and `app.bsky.*` are canonically versioned in this repo, for now, under `./lexicons/`. These are JSON files in the [Lexicon schema definition language](https://atproto.com/specs/lexicon), similar to JSON Schema or OpenAPI. -While we do accept contributions, we prioritize high-quality issues and pull requests. Adhering to the below guidelines will ensure a more timely review. +**Interoperability Test Data:** the language-neutral test files in `./interop-test-files/` may be useful for other protocol implementations to ensure that they follow the specification correctly -### Rules: +The source code for the Bluesky Social client app (for web and mobile) can be found at [bluesky-social/social-app](https://github.com/bluesky-social/social-app). + +Go programming language source code is in [bluesky-social/indigo](https://github.com/bluesky-social/indigo), including the BGS implementation. + +## Developer Quickstart + +We recommend [`nvm`](https://github.com/nvm-sh/nvm) for managing Node.js installs. This project requires Node.js version 18. `pnpm` is used to manage the workspace of multiple packages. You can install it with `npm install --global pnpm`. + +There is a Makefile which can help with basic development tasks: + +```shell +# use existing nvm to install node 18 and pnpm +make nvm-setup + +# pull dependencies and build all local packages +make deps +make build + +# run the tests, using Docker services as needed +make test + +# run a local PDS and AppView with fake test accounts and data +make run-dev-env + +# show all other commands +make help +``` + +## About AT Protocol + +The Authenticated Transfer Protocol ("ATP" or "atproto") is a decentralized social media protocol, developed by [Bluesky PBC](https://blueskyweb.xyz). Learn more at: + +- [Overview and Guides](https://atproto.com/guides/overview) 👈 Best starting point +- [Github Discussions](https://github.com/bluesky-social/atproto/discussions) 👈 Great place to ask questions +- [Protocol Specifications](https://atproto.com/specs/atp) +- [Blogpost on self-authenticating data structures](https://blueskyweb.xyz/blog/3-6-2022-a-self-authenticating-social-protocol) + +The Bluesky Social application encompasses a set of schemas and APIs built in the overall AT Protocol framework. The namespace for these "Lexicons" is `app.bsky.*`. + +## Contributions + +> While we do accept contributions, we prioritize high quality issues and pull requests. Adhering to the below guidelines will ensure a more timely review. + +**Rules:** - We may not respond to your issue or PR. - We may close an issue or PR without much feedback. - We may lock discussions or contributions if our attention is getting DDOSed. +- We do not provide support for build issues. -### Guidelines: +**Guidelines:** - Check for existing issues before filing a new one, please. - Open an issue and give some time for discussion before submitting a PR. - If submitting a PR that includes a lexicon change, please get sign off on the lexicon change _before_ doing the implementation. -- Issues are for bugs & feature requests related to the TypeScript implementation of atproto and related services. For high-level discussions, please you the [Discussion Forum](https://github.com/bluesky-social/atproto/discussions). For client issues, please use the relevant [social-app](https://github.com/bluesky-social/social-app) repo +- Issues are for bugs & feature requests related to the TypeScript implementation of atproto and related services. + - For high-level discussions, please use the [Discussion Forum](https://github.com/bluesky-social/atproto/discussions). + - For client issues, please use the relevant [social-app](https://github.com/bluesky-social/social-app) repo. - Stay away from PRs that: - Refactor large parts of the codebase - Add entirely new features without prior discussion @@ -52,6 +108,4 @@ If you discover any security issues, please send an email to security@bsky.app. ## License -MIT License - -Copyright (c) 2023 Bluesky PBC +MIT License. See [LICENSE](./LICENSE) for full text.