So, you're captivated by the fediverse—the decentralized social web powered by protocols like ActivityPub. Maybe you're dreaming of building the next great federated app, a unique space connected to Mastodon, Lemmy, Pixelfed, and more. The temptation to dive deep and implement ActivityPub yourself, from the ground up, is strong. Total control, right? Understanding every byte? Sounds cool!

But hold on a sec. Before you embark on that epic quest, let's talk reality. Implementing ActivityPub correctly isn't just one task; it's like juggling several complex standards while riding a unicycle… blindfolded. It’s hard.

That's where Fedify comes in. It's a TypeScript framework designed to handle the gnarliest parts of ActivityPub development, letting you focus on what makes your app special, not reinventing the federation wheel.

This post will break down the common headaches of DIY ActivityPub implementation and show how Fedify acts as the super-powered pain reliever, starting with the very foundation of how data is represented.

Challenge #1: Data Modeling—Speaking ActivityStreams & JSON-LD Fluently

At its core, ActivityPub relies on the ActivityStreams 2.0 vocabulary to describe actions and objects, and it uses JSON-LD as the syntax to encode this vocabulary. While powerful, this combination introduces significant complexity right from the start.

First, understanding and correctly using the vast ActivityStreams vocabulary itself is a hurdle. You need to model everything—posts (Note, Article), profiles (Person, Organization), actions (Create, Follow, Like, Announce)—using the precise terms and properties defined in the specification. Manual JSON construction is tedious and prone to errors.

Second, JSON-LD, the encoding layer, has specific rules that make direct JSON manipulation surprisingly tricky:

• Missing vs. Empty Array: In JSON-LD, a property being absent is often semantically identical to it being present with an empty array. Your application logic needs to treat these cases equally when checking for values. For example, these two Note objects mean the same thing regarding the name property:

  // No name property
  {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Note",
    "content": "…"
  }

  // Equivalent to:
  {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Note",
    "name": [],
    "content": "…"
  }

• Single Value vs. Array: Similarly, a property holding a single value directly is often equivalent to it holding a single-element array containing that value. Your code must anticipate both representations for the same meaning, like for the content property here:

  // Single value
  {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Note",
    "content": "Hello"
  }

  // Equivalent to:
  {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Note",
    "content": ["Hello"]
  }

• Object Reference vs. Embedded Object: Properties can contain either the full JSON-LD object embedded directly or just a URI string referencing that object. Your application needs to be prepared to fetch the object's data if only a URI is given (a process called dereferencing). These two Announce activities are semantically equivalent (assuming the URIs resolve correctly):

  {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Announce",
    // Embedded objects:
    "actor": {
      "type": "Person",
      "id": "http://sally.example.org/",
      "name": "Sally"
    },
    "object": {
      "type": "Arrive",
      "id": "https://sally.example.com/arrive",
      /* ... */
    }
  }

  // Equivalent to:
  {
    "@context":
    "https://www.w3.org/ns/activitystreams",
    "type": "Announce",
    // URI references:
    "actor": "http://sally.example.org/",
    "object": "https://sally.example.com/arrive"
  }

Attempting to manually handle all these vocabulary rules and JSON-LD variations consistently across your application inevitably leads to verbose, complex, and fragile code, ripe for subtle bugs that break federation.

Fedify tackles this entire data modeling challenge with its comprehensive, type-safe Activity Vocabulary API. It provides TypeScript classes for ActivityStreams types and common extensions, giving you autocompletion and compile-time safety. Crucially, these classes internally manage all the tricky JSON-LD nuances. Fedify's property accessors present a consistent interface—non-functional properties (like tags) always return arrays, functional properties (like content) always return single values or null. It handles object references versus embedded objects seamlessly through dereferencing accessors (like activity.getActor()) which automatically fetch remote objects via URI when needed—a feature known as property hydration. With Fedify, you work with a clean, predictable TypeScript API, letting the framework handle the messy details of AS vocabulary and JSON-LD encoding.

Challenge #2: Discovery & Identity—Finding Your Actors

Once you can model data, you need to make your actors discoverable. This primarily involves the WebFinger protocol (RFC 7033). You'd need to build a server endpoint at /.well-known/webfinger capable of parsing resource queries (like acct: URIs), validating the requested domain against your server, and responding with a precisely formatted JSON Resource Descriptor (JRD). This JRD must include specific links, like a self link pointing to the actor's ActivityPub ID using the correct media type. Getting any part of this wrong can make your actors invisible.

Fedify simplifies this significantly. It automatically handles WebFinger requests based on the actor information you provide through its setActorDispatcher() method. Fedify generates the correct JRD response. If you need more advanced control, like mapping user-facing handles to internal identifiers, you can easily register mapHandle() or mapAlias() callbacks. You focus on defining your actors; Fedify handles making them discoverable.

// Example: Define how to find actors
federation.setActorDispatcher(
  "/users/{username}",
  async (ctx, username) => { /* ... */ }
);
// Now GET /.well-known/webfinger?resource=acct:username@your.domain just works!

Challenge #3: Core ActivityPub Mechanics—Handling Requests and Collections

Serving actor profiles requires careful content negotiation. A request for an actor's ID needs JSON-LD for machine clients (Accept: application/activity+json) but HTML for browsers (Accept: text/html). Handling incoming activities at the inbox endpoint involves validating POST requests, verifying cryptographic signatures, parsing the payload, preventing duplicates (idempotency), and routing based on activity type. Implementing collections (outbox, followers, etc.) with correct pagination adds another layer.

Fedify streamlines all of this. Its core request handler (via Federation.fetch() or framework adapters like @fedify/express) manages content negotiation. You define actors with setActorDispatcher() and web pages with your framework (Hono, Express, SvelteKit, etc.)—Fedify routes appropriately. For the inbox, setInboxListeners() lets you define handlers per activity type (e.g., .on(Follow, ...)), while Fedify automatically handles validation, signature verification, parsing, and idempotency checks using its KV Store. Collection implementation is simplified via dispatchers (e.g., setFollowersDispatcher()); you provide logic to fetch a page of data, and Fedify constructs the correct Collection or CollectionPage with pagination.

// Define inbox handlers
federation.setInboxListeners("/inbox", "/users/{handle}/inbox")
  .on(Follow, async (ctx, follow) => { /* Handle follow */ })
  .on(Undo, async (ctx, undo) => { /* Handle undo */ });

// Define followers collection logic
federation.setFollowersDispatcher(
  "/users/{handle}/followers",
  async (ctx, handle, cursor) => { /* ... */ }
);

Challenge #4: Reliable Delivery & Asynchronous Processing—Sending Activities Robustly

Sending an activity requires more than a simple POST. Networks fail, servers go down. You need robust failure handling and retry logic (ideally with backoff). Processing incoming activities synchronously can block your server. Efficiently broadcasting to many followers (fan-out) requires background processing and using shared inboxes where possible.

Fedify addresses reliability and scalability using its MessageQueue abstraction. When configured (highly recommended), Context.sendActivity() enqueues delivery tasks. Background workers handle sending with automatic retries based on configurable policies (like outboxRetryPolicy). Fedify supports various queue backends (Deno KV, Redis, PostgreSQL, AMQP). For high-traffic fan-out, Fedify uses an optimized two-stage mechanism to distribute the load efficiently.

// Configure Fedify with a persistent queue (e.g., Deno KV)
const federation = createFederation({
  queue: new DenoKvMessageQueue(/* ... */),
  // ...
});
// Sending is now reliable and non-blocking
await ctx.sendActivity({ handle: "myUser" }, recipient, someActivity);

Challenge #5: Security—Avoiding Common Pitfalls

Securing an ActivityPub server is critical. You need to implement HTTP Signatures (draft-cavage-http-signatures-12) for server-to-server authentication—a complex process. You might also need Linked Data Signatures (LDS) or Object Integrity Proofs (OIP) based on FEP-8b32 for data integrity and compatibility. Managing cryptographic keys securely is essential. Lastly, fetching remote resources risks Server-Side Request Forgery (SSRF) if not validated properly.

Fedify is designed with security in mind. It automatically handles the creation and verification of HTTP Signatures, LDS, and OIP, provided you supply keys via setKeyPairsDispatcher(). It includes key management utilities. Crucially, Fedify's default document loader includes built-in SSRF protection, blocking requests to private IPs unless explicitly allowed.

Challenge #6: Interoperability & Maintenance—Playing Nicely with Others

The fediverse is diverse. Different servers have quirks. Ensuring compatibility requires testing and adaptation. Standards evolve with new Federation Enhancement Proposals (FEPs). You also need protocols like NodeInfo to advertise server capabilities.

Fedify aims for broad interoperability and is actively maintained. It includes features like ActivityTransformers to smooth over implementation differences. NodeInfo support is built-in via setNodeInfoDispatcher().

Challenge #7: Developer Experience—Actually Building Your App

Beyond the protocol, building any server involves setup, testing, and debugging. With federation, debugging becomes harder—was the message malformed? Was the signature wrong? Is the remote server down? Is it a compatibility quirk? Good tooling is essential.

Fedify enhances the developer experience significantly. Being built with TypeScript, it offers excellent type safety and editor auto-completion. The fedify CLI is a powerful companion designed to streamline common development tasks.

You can quickly scaffold a new project tailored to your chosen runtime and web framework using fedify init.

For debugging interactions and verifying data, fedify lookup is invaluable. It lets you inspect how any remote actor or object appears from the outside by performing WebFinger discovery and fetching the object's data. Fedify then displays the parsed object structure and properties directly in your terminal. For example, running:

$ fedify lookup @fedify-example@fedify-blog.deno.dev

Will first show progress messages and then output the structured representation of the actor, similar to this:

// Output of fedify lookup command (shows parsed object structure)
Person {
  id: URL "https://fedify-blog.deno.dev/users/fedify-example",
  name: "Fedify Example Blog",
  published: 2024-03-03T13:18:11.857Z, // Simplified timestamp
  summary: "This blog is powered by Fedify, a fediverse server framework.",
  url: URL "https://fedify-blog.deno.dev/",
  preferredUsername: "fedify-example",
  publicKey: CryptographicKey {
    id: URL "https://fedify-blog.deno.dev/users/fedify-example#main-key",
    owner: URL "https://fedify-blog.deno.dev/users/fedify-example",
    publicKey: CryptoKey { /* ... CryptoKey details ... */ }
  },
  // ... other properties like inbox, outbox, followers, endpoints ...
}

This allows you to easily check how data is structured or troubleshoot why an interaction might be failing by seeing the actual properties Fedify parsed.

Testing outgoing activities from your application during development is made much easier with fedify inbox. Running the command starts a temporary local server that acts as a publicly accessible inbox, displaying key information about the temporary actor it creates for receiving messages:

$ fedify inbox
✔ The ephemeral ActivityPub server is up and running: https://<unique_id>.lhr.life/
✔ Sent follow request to @<some_test_account>@activitypub.academy.
╭───────────────┬─────────────────────────────────────────╮
│ Actor handle: │ i@<unique_id>.lhr.life                  │
├───────────────┼─────────────────────────────────────────┤
│   Actor URI:  │ https://<unique_id>.lhr.life/i          │
├───────────────┼─────────────────────────────────────────┤
│  Actor inbox: │ https://<unique_id>.lhr.life/i/inbox    │
├───────────────┼─────────────────────────────────────────┤
│ Shared inbox: │ https://<unique_id>.lhr.life/inbox      │
╰───────────────┴─────────────────────────────────────────╯

Web interface available at: http://localhost:8000/

You then configure your developing application to send an activity to the Actor inbox or Shared inbox URI provided. When an activity arrives, fedify inbox only prints a summary table to your console indicating that a request was received:

╭────────────────┬─────────────────────────────────────╮
│     Request #: │ 2                                   │
├────────────────┼─────────────────────────────────────┤
│ Activity type: │ Follow                              │
├────────────────┼─────────────────────────────────────┤
│  HTTP request: │ POST /i/inbox                       │
├────────────────┼─────────────────────────────────────┤
│ HTTP response: │ 202                                 │
├────────────────┼─────────────────────────────────────┤
│       Details  │ https://<unique_id>.lhr.life/r/2    │
╰────────────────┴─────────────────────────────────────╯

Crucially, the detailed information about the received request—including the full headers (like Signature), the request body (the Activity JSON), and the signature verification status—is only available in the web interface provided by fedify inbox. This web UI allows you to thoroughly inspect incoming activities during development.

When you need to test interactions with the live fediverse from your local machine beyond just sending, fedify tunnel can securely expose your entire local development server temporarily. This suite of tools significantly eases the process of building and debugging federated applications.

Conclusion: Build Features, Not Plumbing

Implementing the ActivityPub suite of protocols from scratch is an incredibly complex and time-consuming undertaking. It involves deep dives into multiple technical specifications, cryptographic signing, security hardening, and navigating the nuances of a diverse ecosystem. While educational, it dramatically slows down the process of building the actual, unique features of your federated application.

Fedify offers a well-architected, secure, and type-safe foundation, handling the intricacies of federation for you—data modeling, discovery, core mechanics, delivery, security, and interoperability. It lets you focus on your application's unique value and user experience. Stop wrestling with low-level protocol details and start building your vision for the fediverse faster and more reliably. Give Fedify a try!

Getting started is straightforward. First, install the Fedify CLI using your preferred method. Once installed, create a new project template by running fedify init your-project-name.

Check out the Fedify tutorials and Fedify manual to learn more. Happy federating!

안녕하세요! 오늘은 제가 개발한 deno-task-hooks 패키지를 소개해 드리려고 합니다. 이 도구는 Deno 태스크를 Git 훅으로 사용할 수 있게 해주는 간단하면서도 유용한 패키지입니다.

어떤 문제를 해결하나요?

Git을 사용하는 개발 팀에서는 코드 품질 유지를 위해 커밋이나 푸시 전에 린트, 테스트 등의 검증 작업을 실행하는 것이 일반적입니다. 이러한 작업은 Git 훅을 통해 자동화할 수 있지만, 기존 방식에는 몇 가지 문제가 있었습니다:

• Git 훅 스크립트를 팀원들과 공유하기 어려움 (.git 디렉토리는 보통 버전 관리에서 제외됨)
• 각 개발자가 로컬에서 훅을 직접 설정해야 하는 번거로움
• 훅 스크립트의 일관성 유지가 어려움

deno-task-hooks는 이러한 문제를 해결하기 위해 Deno의 태스크 러너를 활용합니다. Deno 태스크는 deno.json 파일에 정의되어 버전 관리가 가능하므로, 팀 전체가 동일한 Git 훅을 쉽게 공유할 수 있습니다.

어떻게 작동하나요?

deno-task-hooks의 작동 방식은 간단합니다:

1. deno.json 파일에 Git 훅으로 사용할 Deno 태스크를 정의합니다.
2. hooks:install 태스크를 실행하면, 정의된 태스크들이 자동으로 .git/hooks/ 디렉토리에 설치됩니다.
3. 이후 Git 작업 시 해당 훅이 트리거되면 연결된 Deno 태스크가 실행됩니다.

설치 및 사용 방법

1. hooks:install 태스크 추가하기

먼저 deno.json 파일에 hooks:install 태스크를 추가합니다:

{
  "tasks": {
    "hooks:install": "deno run --allow-read=deno.json,.git/hooks/ --allow-write=.git/hooks/ jsr:@hongminhee/deno-task-hooks"
  }
}

2. Git 훅 정의하기

Git 훅은 hooks: 접두사 다음에 훅 이름(케밥 케이스)을 붙여 정의합니다. 예를 들어, pre-commit 훅을 정의하려면:

{
  "tasks": {
    "hooks:pre-commit": "deno check *.ts && deno lint"
  }
}

3. 훅 설치하기

다음 명령어를 실행하여 정의된 훅을 설치합니다:

deno task hooks:install

이제 Git 커밋을 실행할 때마다 pre-commit 훅이 자동으로 실행되어 TypeScript 파일을 검사하고 린트 검사를 수행합니다.

지원되는 Git 훅 종류

deno-task-hooks는 다음과 같은 모든 Git 훅 타입을 지원합니다:

• applypatch-msg
• commit-msg
• fsmonitor-watchman
• post-update
• pre-applypatch
• pre-commit
• pre-merge-commit
• pre-push
• pre-rebase
• pre-receive
• prepare-commit-msg
• push-to-checkout
• sendemail-validate
• update

이점

deno-task-hooks를 사용하면 다음과 같은 이점이 있습니다:

1. 간편한 공유: Git 훅을 deno.json 파일에 정의하여 팀 전체가 동일한 훅을 사용할 수 있습니다.
2. 설정 용이성: 새 팀원은 저장소를 클론한 후 한 번의 명령어로 모든 훅을 설치할 수 있습니다.
3. 유지 관리 용이성: 훅 스크립트를 중앙에서 관리하므로 변경 사항을 쉽게 추적하고 적용할 수 있습니다.
4. Deno의 안전성: Deno의 권한 모델을 활용하여 훅 스크립트의 보안을 강화할 수 있습니다.

마치며

deno-task-hooks는 작은 패키지이지만, Git과 Deno를 함께 사용하는 팀의 개발 경험을 크게 향상시킬 수 있습니다. 코드 품질 유지와 개발 워크플로우 자동화를 위해 한번 사용해 보세요!

패키지는 JSR에서 다운로드할 수 있으며, GitHub에서 소스 코드를 확인할 수 있습니다.

피드백과 기여는 언제나 환영합니다! 😊

인용: https://hackers.pub/@bgl/0195f0eb-88dd-77e3-a864-f0371e85b270

스태키지(Stackage)는 하스켈이 (의외로) 성공하여 해키지(Hackage)가 거대해지자, 그 거대함 때문에 발생하는 불편을 해소하는 한 방책으로 고안되었습니다. 그런데 당시에 해키지만큼 거대한 생태계를 갖추고 있으면서 동시에 "컴파일이 성공한다면 실행도 아마 성공할 것"이라는 훌륭한 속성을 갖는 언어는 달리 없었죠. 러스트가 있지 않으냐? 스태키지가 처음 나온 게 2012년입니다. 러스트는 아직 crates.io 도 자리잡기 전이었죠. (사실 이 시점의 러스트는 지금과는 언어 자체가 많이 다른 언어였고요.)

하스켈의 패키지 버저닝 정책에 따르면, 후방호환성 깨지는 변경은 반드시 메이저 버전을 올려야 하고, 마이너 버전만 올리는 변경은 후방호환성 유지될 때에만 가능합니다. 이런 정책 당연히 좋지만, 사람이 내용을 잘 숙지하고 지켜야 의미가 있습니다. 후방호환성을 깨면서 마이너 버전만 올리는 실수는 어떤 개발자든 할 수 있죠.

그런데 하스켈의 경우, 인간이 실수해도 기계가 잡아 줄 여지가 처음부터 매우 큰 언어이고, 예를 들어 어떤 함수가 핵미사일을 발사할 수 있는지 아닌지를 함수 실행 없이도 식별할 수 있는 언어라고들 하죠. 하스켈의 마지막 표준이 2010년에 나왔으니 2010년을 기준으로 하면, 당시 하스켈이 제공하는 "컴파일 시간 보장"의 범위는 그야말로 독보적이었습니다. (하스켈보다 더 강한 보장을 제공하는 언어들은 있었지만, 그만한 라이브러리 에코시스템이 없었고요.)

그래서 스태키지라는 모형이 의미가 있었습니다. A라는 패키지의 새 마이너 버전이 해키지에 올라오면, 스태키지에서 자동으로 가져갑니다. 스태키지는 같은 큐레이션에 포함된 다른 패키지들 중 A에 의존하는 패키지들을 추리고, 얘네한테 A의 새 버전을 먹여도 빌드가 잘 되는지 검사합니다. 이들 중 하나라도 깨지면? A 패키지는 해키지에서는 버전이 올랐으나, 스태키지에서는 버전이 오르지 않게 됩니다. 그리고 A 패키지의 제공자에게 자동으로 깃허브 멘션 알림이 갑니다!

("패키지 저자"와 "패키지를 스태키지에 제공하는 제공자"가 같은 사람이 아니어도 된다는 점도, 노동력의 효과적 분담에 한몫했습니다.)

이 모든 과정이 자동화되어 있는데, 이것만으로도 99.99%의 호환성 문제가 사라지고, 그러면서도 웬만한 라이브러리들은 충분히 최신 버전으로 쓸 수 있습니다. LTS와 나이틀리가 구분되어 있는 것도, LTS가 GHC 버전에 대응하여 여러 버전이 유지되는 것도, 실제 개발에서 아주 편리하고요.

스태키지가 개쩌는 부분은 "버저닝 정책에 완벽하게 부합하는데도 현실적으로 후방호환성 파괴를 일으키는" 변경점들도 잡아낸다는 것입니다. 아주 단순한 예시로 "많이 쓰이는 이름"이 있습니다. 예를 들어 어떤 라이브러리가 아주 널리 쓰이는데, 제공하는 네임 바인딩은 몇 개 안 되고, 그래서 대부분의 사용자가 그걸 그냥 전역 네임스페이스에 다 반입해서 쓴다고 칩시다. 어느 날 이 라이브러리가 process 라든지 f 같은 새 네임을 추가 제공하기 시작하면? 정책 규범에 따르면, 이것도 마이너 버전만 올려도 되는 변경점이 맞습니다. 하지만 현실에서는 많은 패키지들을 박살내겠죠. 언어를 막론하고 있을 수 있는 일인데, 이런 것들까지 스태키지에서 아주 높은 확률로 다 잡힙니다.

그리고... 이런 게 잘 된다는 것은 언어 그 자체의 특성도 있지만, 생태계 전체의 문화적인 특성도 있는데요. 하스켈도 라이브러리 제작자가 충분히 악독하다면, 컴파일러에게 안 잡히면서 인류문명멸망시키는 코드 변경을 얼마든지 슬쩍 끼워넣을 수 있습니다. 악의가 아니더라도 부주의로 후방호환성을 깰 수 있고요. 그런데 하스켈은 대부분의 라이브러리 설계자들이 "되도록 많은 것을 컴파일 시간에 잡고 싶다"라는 명확한 욕망으로 설계를 하는 경향이 뚜렷합니다. 그래서 호환성 문제는 웬만하면 스태키지 선에서 잡히고, 스태키지 큐레이션은 지난 10년 동안 실무상 아주 유용한 도구로 기능해 온 것이죠.

어지간하면 큐레이션만 잘 고르고 잘 갱신하면 되고, 종속성 목록에는 mypkg >= 2.1.1 && < 2.1.2 이런 거 하나도 관리 안 하고 그냥 mypkg 라고만 써도 된다는 것이, 솔직히 개짱편합니다. 다행히 지난 10년 동안 "문제의 소지는 컴파일 시간에 검출하는 게 좋다"라는 생각이 더 널리 받아들여져서, 다른 언어들도 이런 접근을 더 시도할 여지가 생긴 것 같군요.