ActivityPub 액터 구현

Status: Experiment
Self-Managed형 GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용하려면 관리자가 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"를 사용하여 이루어집니다.

우리가 구현한 액터들:

계획된 액터에 대한 자세한 정보는 epic 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 어휘 문서에 문서화되어 있습니다. 선택한 리소스 유형에 따라 상속된 속성 또는 직접 사용할 수 있는 모든 속성을 알려주는 properties 디렉터리을 찾으세요.

Mastodon은 preferredName이라는 하나의 속성을 추가합니다. Mastodon은 이것이 모든 액터에 설정되거나 그 액터는 Mastodon에서 인식되지 않습니다.