ActivityPub 액터 구현하기

요약

GitLab Self-Managed에서는 기본적으로 이 기능을 사용할 수 없습니다. 이 기능에는 두 개의 기능 플래그가 필요합니다: activity_pub: 모든 ActivityPub 관련 기능을 활성화하거나 비활성화합니다.

Status: Experiment

히스토리

GitLab 16.5에서 activity_pub 및 activity_pub_project라는 두 개의 플래그와 함께 도입됨. 기본적으로 비활성화되어 있음. 이 기능은 실험 기능입니다.

GitLab Self-Managed에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용 가능하게 하려면, 관리자가 activity_pub 및 activity_pub_project라는 기능 플래그를 활성화할 수 있습니다. GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다. 이 기능은 프로덕션 환경에서 사용할 준비가 되어 있지 않습니다.

이 기능에는 두 개의 기능 플래그가 필요합니다:

activity_pub: 모든 ActivityPub 관련 기능을 활성화하거나 비활성화합니다.
activity_pub_project: 프로젝트에 특화된 ActivityPub 기능을 활성화하거나 비활성화합니다. activity_pub 플래그도 함께 활성화해야 합니다.

ActivityPub은 세 가지 표준 문서를 기반으로 합니다:

ActivityPub은 페더레이션을 구현하기 위해 발생하는 HTTP 요청을 정의합니다.
ActivityStreams는 프로토콜 사용자들이 교환하는 JSON 메시지의 형식을 정의합니다.
Activity Vocabulary는 기본적으로 인식되는 다양한 메시지를 정의합니다.

첫 번째 문서는 일반적으로 컨트롤러가 처리하며, 나머지 두 개는 시리얼라이저에서 처리하는 내용과 관련이 있습니다.

ActivityPub 액터를 구현하려면 다음을 수행해야 합니다:

리소스의 프로필 페이지를 구현합니다.
아웃박스 페이지를 구현합니다.
인박스에서 들어오는 요청을 처리합니다.

모든 요청은 Accept HTTP 헤더로 application/ld+json; profile="https://www.w3.org/ns/activitystreams"를 사용하여 이루어집니다.

소셜 기능을 위해 구현한 액터:

릴리즈

계획된 액터에 대한 자세한 내용은 에픽 11247을 참조하세요.

프로필 페이지#

프로필 페이지 조회는 다음을 검색하는 데 사용됩니다:

이름과 설명 같은 일반적인 정보.
인박스 및 아웃박스의 URL.

프로필 페이지를 구현하려면, app/serializers/activity_pub/에 ActivityStreams 시리얼라이저를 생성하여 시리얼라이저가 ActivityStreamsSerializer를 상속받도록 만드세요. 필수 필드에 대해서는 아래 시리얼라이저 섹션을 참조하세요.

컨트롤러에서 시리얼라이저를 호출하려면:

opts = {
  inbox: nil,
  outbox: outbox_project_releases_url(project)
}

render json: ActivityPub::ReleasesActorSerializer.new.represent(project, opts)

outbox는 이 액터의 활동 피드를 찾을 수 있는 엔드포인트입니다.
inbox는 피드를 구독하기 위해 POST 요청을 보내는 곳입니다. 아직 구현되지 않았으므로 nil을 전달하세요.

아웃박스 페이지#

아웃박스는 리소스에 대한 활동 목록입니다. 리소스의 피드 역할을 하며, ActivityPub 클라이언트가 아직 구독하지 않고도 이 액터의 공개 활동을 확인할 수 있게 해줍니다.

아웃박스 페이지를 구현하려면, app/serializers/activity_pub/에 ActivityStreams 시리얼라이저를 생성하여 시리얼라이저가 ActivityStreamsSerializer를 상속받도록 만드세요. 필수 필드에 대해서는 아래 시리얼라이저 섹션을 참조하세요.

컨트롤러에서 시리얼라이저를 다음과 같이 호출합니다:

serializer = ActivityPub::ReleasesOutboxSerializer.new.with_pagination(request, response)
render json: serializer.represent(releases)

이것은 응답을 모든 올바른 필드를 갖춘 OrderedCollection ActivityPub 타입으로 변환합니다.

인박스#

아직 구현되지 않았습니다.

인박스는 ActivityPub 호환 서드파티가 액터를 구독하거나 메시지를 보내기 위해 요청을 보내는 곳입니다.

ActivityStreams 시리얼라이저#

시리얼라이저는 ActivityPub 지원의 핵심 절반을 구현합니다: 모두 ActivityPub에서 사용하는 메시지 형식인 ActivityStreams에 관한 것입니다.

대부분의 형식 지정을 처리하는 기능을 활용하려면, 시리얼라이저가 ActivityPub::ActivityStreamsSerializer를 상속받아야 합니다.

사용하려면 #represent 메서드를 호출하세요. 액터 프로필 페이지인 경우 inbox 및 outbox 옵션을 제공해야 합니다(위에서 언급한 대로). 시리얼라이저가 사용자의 연락처 정보를 나타내는 객체처럼 액터의 일부로 임베드되도록 설계된 객체를 나타내는 경우에는 해당 옵션이 필요하지 않습니다.

시리얼라이즈되는 각 리소스(액터에 임베드된 다른 객체 포함)는 id와 type 필드를 제공해야 합니다.

id는 URL입니다. 리소스의 고유 식별자를 의미하며, 기존 페이지(이상적으로는 액터)를 가리켜야 합니다. 그렇지 않으면 다음과 같이 가장 가까운 액터를 참조하고 앵커를 사용하면 됩니다:

https://gitlab.com/user/project/-/releases#release-1

type은 ActivityStreams 핵심 어휘에서 가져와야 합니다:

사용할 수 있는 속성은 모두 ActivityStreams vocabulary 문서에 문서화되어 있습니다. 리소스에 대해 선택한 타입에 따라 properties 목록을 찾아보면, 직접적이거나 상속된 모든 사용 가능한 속성을 알 수 있습니다.

Mastodon이 preferredName이라는 속성을 하나 더 추가한다는 점을 알아두는 것이 좋습니다. Mastodon은 이 속성이 모든 액터에 설정되어 있기를 기대하며, 설정되어 있지 않으면 Mastodon에서 해당 액터를 인식하지 못합니다.