-
Notifications
You must be signed in to change notification settings - Fork 580
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
74 additions
and
26 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,94 @@ | ||
| # 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 the `app.bsky` microblogging application services. | ||
|
|
||
| --- | ||
|
|
||
| **⚠️ 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) | [](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) | [](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) | [](https://www.npmjs.com/package/@atproto/common) | | ||
| | `@atproto/crypto`: | [README](./packages/crypto/README.md) | [](https://www.npmjs.com/package/@atproto/crypto) | | ||
| | `@atproto/identity`: DID and handle resolution | [README](./packages/identity/README.md) | [](https://www.npmjs.com/package/@atproto/identity) | | ||
| | `@atproto/lexicon`: schema definition language | [README](./packages/lexicon/README.md) | [](https://www.npmjs.com/package/@atproto/lexicon) | | ||
| | `@atproto/repo`: data storage structure, including MST | [README](./packages/repo/README.md) | [](https://www.npmjs.com/package/@atproto/repo) | | ||
| | `@atproto/syntax`: string parsers for identifiers | [README](./packages/syntax/README.md) | [](https://www.npmjs.com/package/@atproto/syntax) | | ||
| | `@atproto/xrpc`: client-side HTTP API helpers | [README](./packages/xrpc/README.md) | [](https://www.npmjs.com/package/@atproto/xrpc) | | ||
| | `@atproto/xrpc-server`: server-side HTTP API helpers | [README](./packages/xrpc-server/README.md) | [](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). | ||
|
|
||
|
|
||
| ## Developer Quickstart | ||
|
|
||
| You'll need Node.js version 18; we recommend [`nvm`](https://github.com/nvm-sh/nvm) for managing Node installation. This repository uses `pnpm` to manage multiple packages, which you can install 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're not going to provide support for build issues. | ||
|
|
||
| ### Guidelines: | ||
| **Guidelines:** | ||
|
|
||
| - Check for existing issues before filing a new one, please. | ||
| - 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 | ||
| - Stay away from PRs that: | ||
| - Refactor large parts of the codebase | ||
| - Add entirely new features without prior discussion | ||
| - Change the tooling or frameworks used without prior discussion | ||
| - Introduce new unnecessary dependencies | ||
| - Stay away from PRs like... | ||
| - Changing "Post" to "Skeet." | ||
| - Refactoring the codebase, eg to replace mobx with redux or something. | ||
| - Adding entirely new features without prior discussion. | ||
|
|
||
| Remember, we serve a wide community of users. Our day-to-day involves us constantly asking "which top priority is our top priority." If you submit well-written PRs that solve problems concisely, that's an awesome contribution. Otherwise, as much as we'd love to accept your ideas and contributions, we really don't have the bandwidth. | ||
| Remember, we serve a wide community of users. Our day to day involves us constantly asking "which top priority is our top priority." If you submit well-written PRs that solve problems concisely, that's an awesome contribution. Otherwise, as much as we'd love to accept your ideas and contributions, we really don't have the bandwidth. That's what forking is for! | ||
|
|
||
| ## Are you a developer interested in building on atproto? | ||
|
|
||
|
|
@@ -52,6 +102,4 @@ If you discover any security issues, please send an email to [email protected]. | |
|
|
||
| ## License | ||
|
|
||
| MIT License | ||
|
|
||
| Copyright (c) 2023 Bluesky PBC | ||
| MIT License. See [LICENSE](./LICENSE) for full text. | ||