ActivityPub 액터 구현

Status: 실험
  • 이 공식은 기본적으로 비활성화되어 있는 두 플래그인 activity_pub 및 activity_pub_project를 사용하여 GitLab 16.5에 소개되었습니다. 기본적으로 비활성화되어 있습니다. 이 기능은 실험입니다.
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 호환 제3 자가 액터의 구독을 신청하거나 메시지를 보내기 위해 요청을 보내는 위치입니다.

ActivityStreams 직렬화기

직렬화기는 ActivityPub 지원의 핵심의 반을 구현합니다. 모두 ActivityStreams에 대한 메시지 형식과 관련이 있습니다.

더 많은 서식을 처리하는 기능을 레버리지하기 위해 직렬라이저는 ActivityPub::ActivityStreamsSerializer에서 상속해야합니다.

이를 사용하려면 #represent 메서드를 호출하십시오. 액터 프로필 페이지인 경우 inbox 및 outbox 옵션을 제공해야합니다(위에서 언급한대로). 사용자의 연락처 정보를 나타내려고 하는 객체처럼 액터의 일부로서만 포함되는 객체를 나타내는 경우에는 필요하지 않습니다.

직렬화된 각 리소스(액터에 포함된 다른 객체를 포함함)는 모두 id 및 type 필드를 제공해야 합니다.

id는 URL입니다. 리소스의 고유 식별자로 사용되며, 기존 페이지로 이동해야합니다. 이상적으로는 액터여야 하지만, 가장 가까운 액터을 참조하고 다음과 같이 앵커를 사용할 수 있습니다. 

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

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

사용할 수있는 속성은 모두 ActivityStreams 어휘 문서에 문서화되어 있습니다. 선택한 리소스 유형을 고려하여, 모든 사용 가능한 속성(직접 또는 상속됨)을 찾아보십시오.

Mastodon은 preferredName이라는 속성을 더 추가합니다. Mastodon은 이 속성이 사용자에게 설정되어 있거나 사용자가 Mastodon에서 인식되지 않는 경우를 기대합니다.