• Banzai 파이프라인
• Reference filters
  • 새 참조 접두사 및 필터 추가
  • 성능
    • 객체 최적화 찾기
    • 노드 필터링 최적화
• 참조 파서

참조 처리

GitLab Flavored Markdown에는 다양한 GitLab 도메인 객체에 대한 참조를 처리할 수 있는 기능이 포함되어 있습니다. 이는 Banzai 파이프라인의 두 가지 추상화, ReferenceFilter 및 ReferenceParser에 의해 구현됩니다. 이 페이지에서는 이러한 것들이 무엇이며 어떻게 사용되며 새로운 필터/파서 쌍을 구현하는 방법에 대해 설명합니다.

각 ReferenceFilter에는 해당하는 ReferenceParser가 있어야 합니다.

두 개의 필터가 동일한 종류의 객체를 찾고 연결하는 경우 (이는 data-reference-type 속성으로 지정됨), 참조 파서가 해당 도메인 객체 유형에 대해 하나만 필요합니다.

Banzai 파이프라인

Banzai 파이프라인은 파이프라인의 마지막 필터 출력에 기반한 :output 키 또는 문자열 HTML 마크업이 포함된 result 해시를 반환합니다.

result 해시는 각 필터에게 전달되어 수정됩니다. 여기에는 다음이 포함됩니다.

• 마지막 필터의 출력에 따라 DocumentFragment 또는 String HTML 마크업을 가진 :output 키
• 각 필터에서 업데이트된 처리를 위해 준비된 DocumentFragment nodes 목록을 가진 :reference_filter_nodes 키

Reference filters

참조가 처리되는 첫 번째 방법은 참조 필터를 사용하는 것입니다. 이들은 마크업 문서에서 짧은 코드 및 URI 참조를 식별하고 이를 나타내는 리소스로의 구조화된 링크로 변환하는 도구입니다.

예를 들어, 클래스 Banzai::Filter::IssueReferenceFilter 는 gitlab-org/gitlab#123 및 https://gitlab.com/gitlab-org/gitlab/-/issues/200048와 같이 이슈에 대한 참조를 처리하는 역할을 합니다.

모든 참조 필터는 HTML::Pipeline::Filter의 인스턴스이며 (자주 간접적으로) Banzai::Filter::ReferenceFilter에서 상속합니다.

HTML::Pipeline::Filter에는 현재 문서를 변형하는 void 메서드인 #call로 구성된 간단한 인터페이스가 있습니다. ReferenceFilter는 #call 메서드를 정의하기 쉽게 하는 메서드를 제공합니다. 그러나 대부분의 참조 필터는 직접이러한 클래스 중 하나에서 상속하지 않고 AbstractReferenceFilter에서 상속받습니다.

AbstractReferenceFilter의 하위 클래스들은 일반적으로 #call을 오버라이드하지 않습니다. 대신, AbstractReferenceFilter의 최소 구현은 다음을 정의해야 합니다.

• .reference_type: 도메인 객체의 유형.

  이것은 일반적으로 키워드이며 생성된 링크의 data-reference-type 속성을 설정하는 데 사용되며 해당 ReferenceParser와의 상호 작용의 중요한 부분입니다 (아래 참조).

• .object_class: 필터가 참조하는 객체 클래스에 대한 참조.

  이는 다음과 같이 사용됩니다.

  • 참조를 찾기 위해 사용되는 정규 표현식을 찾습니다. 클래스에는 참조를 찾는 데 사용되는 두 개의 정규 표현식을 정의해야 합니다: .link_reference_pattern 및 .reference_pattern이 모두 ReferenceFilter.object_sym 값을 가진 이름이 있는 캡처 그룹을 포함해야 합니다.
  • .object_name을 계산합니다.
  • .object_sym (참조 패턴에서의 그룹 이름)을 계산합니다.
• .parse_symbol(string): 텍스트 값을 객체 식별자로 파싱합니다 (기본적으로 #to_i).
• #record_identifier(record): .parse_symbol의 역 (즉, 도메인 객체를 식별자로 변환함)입니다 (기본적으로 #id).
• #url_for_object(object, parent_object): 도메인 객체에 대한 URL을 생성합니다.
• #find_object(parent_object, id): 부모 (보통은 Project) 및 식별자가 주어지면 객체를 찾습니다. 예를 들어, 병합 요청을 위한 참조 필터의 경우에는 project.merge_requests.where(iid: iid)가 될 수 있습니다.

새 참조 접두사 및 필터 추가

새 객체용 참조 필터의 경우, 다음 패턴을 따르는 접두어 형식을 사용합니다: ^<object_type>#, 왜냐하면:

1. 다양한 한 글자 접두사는 사용자들이 추적하기 어렵습니다. 특히 사용률이 낮은 객체 유형에서는 이 기능의 가치가 줄어들 수 있습니다.
2. 적합한 한 글자 접두사가 제한됩니다.
3. 일관된 패턴을 따르면 사용자들이 새 기능의 존재를 추론할 수 있습니다.

새로운 객체 apple에 대한 참조 접두사를 추가하려면, 이름과 ID를 둘 다 가진 참조의 형식은 다음과 같습니다.

• ID에 의한 식별을 위해 ^apple#123.
• 이름에 의한 식별을 위해 ^apple#"Granny Smith".

성능

객체 최적화 찾기

이 기본 구현은 매번 DB 쿼리를 발급할 수도 있는 각 참조에 대해 #find_object를 호출해야 하기 때문에 효율적이지 못합니다. 이러한 이유로 대부분의 참조 필터 구현은 대신 AbstractReferenceFilter에 포함된 최적화를 사용합니다.

AbstractReferenceFilter는 부모 객체에서 도메인 객체의 컬렉션으로의 매핑인 #records_per_parent를 게으르게 초기화된 값으로 제공합니다.

이 메커니즘을 사용하려면 참조 필터는 #parent_records(parent, set_of_identifiers) 메서드를 구현해야 합니다. 이 메서드는 도메인 객체의 열거 가능한 값을 반환해야 합니다.

이러한 클래스는 이를 가능하게 하기 위해 #find_object를 정의할 수 있습니다 (예: IssuableReferenceFilter)와 같이:

def find_object(parent, iid)
  records_per_parent[parent][iid]
end

이로써 쿼리 수가 프로젝트 수에 선형적으로 줄어듭니다. records_per_parent를 호출할 때 parent_records 메서드를 구현해야만 합니다.

노드 필터링 최적화

각 ReferenceFilter는 문서 내 모든 <a> 및 text() 노드를 반복합니다.

모든 노드가 처리되는 것은 아니며, 문서는 우리가 처리하려는 노드에 대해서만 필터링됩니다. 우리는 다음을 건너뜁니다:

• 이미 이전 필터에서 처리된 링크 태그 (그들이 gfm 클래스를 가지고 있다면).
• 우리가 무시하고 싶은 부모 노드를 가진 노드들 (ignore_ancestor_query).
• 빈 줄.
• 빈 href 속성이 있는 링크 태그.

각 ReferenceFilter마다 이러한 노드들을 필터링하는 것을 피하기 위해, 우리는 한 번만 이것을 하고 파이프라인의 결과 해쉬에 결과를 저장합니다 (result[:reference_filter_nodes]).

파이프라인 result는 수정을 위해 각 필터에 전달되므로 ReferenceFilter에서 텍스트나 링크 태그를 대체할 때마다, 필터된 목록 (reference_filter_nodes)은 다음 필터에서 사용하기 위해 업데이트됩니다.

참조 파서

성능 최적화를 위해 경우에 따라 우리는 한 번에 Markdown을 HTML로 렌더링하고 결과를 캐시한 다음 캐시된 값에서 사용자에게 제공합니다. 예를 들어, 이는 노트, 이슈 설명 및 병합 요청 설명에 대해 발생합니다. 이로써 렌더링된 문서는 일부 후속 리더가 볼 수 없어야 하는 리소스를 참조할 수 있습니다.

예를 들어, 이슈를 작성하고 기밀 이슈 #1234을 참조할 수 있습니다. 이는 캐시된 HTML에서 기밀 이슈로 렌더링되며, 그것의 ID, 프로젝트 ID 및 기타 기밀 데이터가 포함된 데이터 속성을 가진 링크로 표시됩니다. 이슈 #1234를 볼 수 있는 권한이 없는 후속 리더도 이를 읽을 수 없어야 하므로, 우리는 이러한 민감한 데이터를 삭제해야 합니다. 이것이 ReferenceParser 클래스가 하는 일입니다.

참조 파서는 이 관계를 광고하는 링크에 의해 처리하는 객체에 연결됩니다 (data-reference-type 속성으로 설정됨). 이것은 ReferenceRedactor 에서 사용자에게 표시되어야 하는 노드를 계산하기 위해 사용됩니다:

def nodes_visible_to_user(nodes)
  per_type = Hash.new { |h, k| h[k] = [] }
  visible = Set.new

  nodes.each do |node|
    per_type[node.attr('data-reference-type')] << node
  end

  per_type.each do |type, nodes|
    parser = Banzai::ReferenceParser[type].new(context)

    visible.merge(parser.nodes_visible_to_user(user, nodes))
  end

  visible
end

여기서 키포인트는 Banzai::ReferenceParser[type]로, 각 도메인 객체의 올바른 참조 파서를 찾기 위해 사용됩니다. 이는 각 참조 파서가 반드시:

• Banzai::ReferenceParser 네임스페이스에 배치되어야 합니다.
• .nodes_visible_to_user(user, nodes) 메서드를 구현해야 합니다.

실제로, 모든 참조 파서는 일반적으로 BaseParser를 상속받고, 다음을 정의함으로써 구현됩니다:

• reference_type를 ReferenceFilter.reference_type와 같아야 합니다.
• 그리고 다음 중 하나 이상을 구현함으로써:
  • 가장 미세한 제어를 위해 #nodes_visible_to_user(user, nodes)를.
  • 만약 nodes_visible_to_user가 재정의되지 않은 경우 필요한 #can_read_reference?.
  • ID별 객체에 대한 액티브 레코드 관계인 #references_relation.
  • 노드를 직접 필터링하기 위한 #nodes_user_can_reference(user, nodes)를.

각 참조 타입에 대해 이 클래스를 구현하지 않은 경우, 응용 프로그램은 Markdown 처리 중에 예외를 발생시킵니다.