핵심 개념
ActivityPlug는 클라이언트 API가 서로 다른 서버에 대해 하나의 TypeScript, HTTP, GraphQL, 브라우저 계약을 제공합니다. 아래 개념은 이식 가능한 동작의 범위와 서버별 동작이 보존되는 범위를 정의합니다.
어댑터
어댑터는 ActivityPlugAdapter를 구현합니다. 어댑터의 메타데이터에는 안정적인 ID, 표시 이름, 어댑터 종류, 인식하는 소프트웨어 제품군, 정적 capability 판정이 포함됩니다. 선택적 작업 그룹은 인스턴스, 계정, 게시물, 타임라인, 검색, 미디어, 투표, 소셜, 알림, 목록, 팔로우 요청, 필터, 예약 게시물, 북마크 폴더, 스트리밍 동작을 구현합니다.
어댑터 ID는 모든 공개 엔티티 ID와 페이지 커서의 일부입니다. 이를 변경하면 이전 버전에서 만든 참조가 깨집니다. 제품별 어댑터는 API 계약을 매핑하지 않은 소프트웨어와의 호환성을 표시해서는 안 됩니다.
인스턴스와 origin
인스턴스는 Fediverse 서버 소프트웨어의 개별 배포입니다. ActivityPlug는 https://social.example 같은 정규 origin으로 인스턴스를 선택합니다. 경로, 쿼리, 프래그먼트, 내장된 인증 정보는 인스턴스 식별자에 포함되지 않습니다.
라이브러리 클라이언트는 하나의 어댑터를 하나의 origin에 바인딩합니다. 서버 요청에는 어댑터·origin 선택자가 포함되므로, 하나의 ActivityPlug 서버에서 여러 소프트웨어 제품군과 배포를 대상으로 요청할 수 있습니다.
인스턴스 탐색은 NodeInfo, OAuth 메타데이터, 제품별 인스턴스 엔드포인트, 명시적 기능 프로브를 조합할 수 있습니다. 탐색 링크는 선택한 인스턴스의 origin 범위 안에 있어야 합니다. 원격 접근에는 구성된 origin·네트워크 정책도 적용됩니다.
세션
AuthSession은 AuthSessionStore 뒤에 저장된 인증 정보를 가리키는 공개 참조입니다. 세션 ID, 어댑터, origin, 인증 전략, 범위, capability 메타데이터, 선택적 계정·만료 정보를 담고 있습니다. 저장된 access token이나 refresh token은 노출하지 않습니다.
세션은 발급한 어댑터·origin에 바인딩됩니다. 다른 어댑터·origin으로 세션을 전달하면 인증이 실패합니다. 지원하는 전략으로 OAuth, 가져온 토큰, 이메일 챌린지, 패스키가 있지만, 각 어댑터는 자신이 구현한 전략만 알립니다.
코어 패키지는 기본적으로 메모리 내 인증 저장소와 credential 임대 저장소를 사용합니다. 서버에는 브라우저, OAuth 상태, 단기 캐시, 스트림 티켓을 위한 추가 저장소가 있습니다. 재시작 후에도 상태를 유지하거나 여러 복제본 사이에서 공유해야 하는 프로덕션 배포에서는, 필요한 내구성과 공유 속성을 갖춘 저장소를 구성해야 합니다.
Capability
Capability는 이식 가능한 동작의 지원 여부를 이름으로 판정한 것입니다. posts.update나 streaming.notifications 등이 있으며, 상태는 다음과 같습니다.
supported: 선택한 어댑터와 알려진 인스턴스 계약이 해당 동작을 지원합니다.unsupported: 해당 동작을 사용할 수 없거나 매핑되지 않은 것으로 확인되었습니다.unknown: 사용 가능한 근거만으로는 지원 여부를 확정할 수 없습니다.
판정에는 이유, 소프트웨어 버전 제약, 허용 입력, 미디어 제한이 포함될 수 있습니다. ActivityPlug는 정적 어댑터 메타데이터, NodeInfo, OAuth 메타데이터, 인스턴스 메타데이터, 프로브 순서로 근거 계층을 병합합니다. 이 순서에서 더 구체적인 계층이 앞선 판정을 대체할 수 있습니다.
Capability 검사는 단순한 UI 힌트가 아니라 동작 계약입니다. 클라이언트 서비스는 필수 capability가 unsupported나 unknown이면 해당 요청을 보내지 않고 거부합니다. 서버나 버전에 따라 동작이 달라질 수 있으므로, 런타임에 판정을 확인하십시오.
엔티티 참조와 불투명 ID
정규화된 엔티티에는 다음 항목으로 구성된 EntityRef가 포함됩니다.
id: 이식 가능한 불투명 ID입니다.type: 정규화된 엔티티 유형입니다.adapter와origin: 엔티티를 소유한 대상입니다.rawId: 어댑터 네이티브 식별자입니다.- 선택적
rawUrl: 원격 리소스 URL입니다.
불투명 ID는 어댑터, origin, 엔티티 유형, 원시 ID를 버전이 지정된 봉투에 인코딩합니다. 분할할 수 없는 단일 공개 값으로 취급하십시오. 클라이언트는 어댑터를 호출하기 전에 이를 디코딩·검증하며, 다른 어댑터·origin·엔티티 유형의 참조는 거부합니다. rawId는 진단이나 명시적인 어댑터 간 상호 운용에만 사용하십시오.
정규화된 엔티티는 원격 원시 데이터인 raw와 이름이 지정된 extensions도 노출할 수 있습니다. 이 필드는 이식 가능한 계약에 포함되지 않습니다.
페이지와 커서
목록 작업은 nodes와 pageInfo가 포함된 Connection<Node>를 반환합니다. PageInput은 after, before, limit을 받습니다. ActivityPlug는 PORTABLE_PAGE_LIMIT을 초과하는 양의 limit를 100으로 제한합니다.
ActivityPlug 커서는 원격 커서를 어댑터, origin, 공개 작업에 바인딩합니다. 커서를 다른 타임라인, 작업, 어댑터, 인스턴스에서 재사용할 수 없습니다. 어댑터는 엔티티 ID에서 커서를 합성하지 말고 원격 API의 정확한 커서를 보존해야 합니다. 원격 엔드포인트가 신뢰할 수 있는 연속 조회를 제공하지 못한다면, 어댑터는 커서 입력을 거부하거나 해당 연속 조회 값을 생략해야 합니다.
오류
이식 가능한 실패에는 ActivityPlugError를 사용합니다. code로 실패를 분류하고, context로 어댑터, origin, 작업, capability, 원격 세부 정보를 식별합니다. 일반적인 범주에는 검증, 인증, 미지원 동작, 원격 프로토콜 오류, 네트워크 실패, origin 정책 거부, 요청 한도 소진이 포함됩니다.
code로 분기하기 전에 isActivityPlugError()를 사용하십시오. 사람이 읽는 메시지를 파싱하지 마십시오. UNSUPPORTED_OPERATION은 명시적인 결과이며, null로 대체하라는 뜻이 아닙니다. 호출자가 지원되는 동작이나 대상을 선택해야 합니다.
원격 권한
모든 원격 작업은 RemoteAuthority를 거칩니다. 요청을 대상과 공개 작업에 바인딩하고, credential이 origin이나 표현을 넘어 전달될 수 있는지 통제합니다. 동일 origin의 credential은 권한에 구성된 표현에 따라 허용됩니다. 교차 origin credential에는 정확한 단방향 허용 규칙이 필요합니다.
라이브러리 사용자는 원격 I/O 전에 권한을 명시적으로 제공해야 합니다. 서버는 origin 검사, DNS 고정, 사설 네트워크 통제, 요청 예산, 응답 제한을 갖춘 검증된 Node.js 권한을 구성합니다. 브라우저 코드는 createBrowserRemoteAuthority()로 브라우저 fetch 경계를 명시적으로 활성화할 수 있습니다.