🇰🇷 한국어 🇺🇸 English

네트워크 피드 호스팅 명세

커뮤니티가 운영하시는 도메인에 news.json 형식의 파일을 호스팅하시면, Loopback Social 봇이 6시간마다 자동으로 가져와 배너와 공용 피드에 노출합니다. 본 문서는 그 자율 게시 경로(홈의 Step 2 옵션 1)를 운영하시려는 커뮤니티 담당자를 위한 가이드입니다.

전체 흐름

운영하시는 도메인에 news.schema.json 형식의 JSON 배열을 게시합니다. 예: https://forum.example.com/loopback.json. 언어별로 분리하시려면 loopback.ko.json / loopback.en.json 두 개로 운영하실 수 있습니다.
커뮤니티 등재 이슈의 "네트워크 뉴스 소스" 칸에 그 URL(들)을 함께 제출합니다.
운영자가 검수 후 머지 → aggregate-network.mjs가 6시간마다 가장 최근 active 항목을 가져옵니다.
이후에는 호스팅하신 파일만 갱신하시면 다음 사이클에 자동 반영됩니다. 별도 PR 불필요.

배너에서는 [커뮤니티 이름] 메시지 형태로 출처가 항상 명시되고, 공용 RSS/Atom/JSON Feed에도 동일한 메타데이터가 포함됩니다.

최소 요구사항

HTTPS로 공개 접근 가능. 등재 양식은 https://로 시작하는 URL만 허용합니다.
본문은 news.schema.json을 따르는 JSON 배열. 항목 형식은 홈의 Step 3 항목 형식과 동일.
응답 본문 1 MB 이내, 10초 안에 응답. 초과 시 그 사이클은 해당 URL을 스킵.
30x 리다이렉트는 자동 추종.

항목 선택 규칙

aggregator는 현재 시각이 start ≤ now ≤ end 안인 active 항목만 후보로 봅니다 (display가 truthy인 항목 한정).
후보를 start 내림차순으로 정렬 후 위에서부터 픽업 (가장 최근에 시작된 항목이 먼저).
network_url이 단일 문자열이면 그 URL에서 top-2. {ko, en} 두 URL이면 각 top-1(언어별 1개씩). 커뮤니티당 최대 2개.
같은 항목이 ko/en URL 양쪽에 등장하면 한 번만 노출됩니다. 정확한 중복 제거를 원하면 항목에 id 필드를 명시. 없으면 start + message의 해시로 dedup.

출처 메타데이터 (`_source`)

픽업된 모든 항목에는 다음 모양의 _source가 자동으로 박혀 들어갑니다. 커뮤니티가 페이로드에 직접 넣은 _source는 덮어쓰입니다.

{
  "_source": {
    "community": "kebab-slug",
    "community_name": { "ko": "닷넷데브", "en": ".NET Dev" },
    "community_url": "https://forum.dotnetdev.kr/",
    "source_url": "https://forum.dotnetdev.kr/loopback.json",
    "lang": "ko"
  }
}

배너 런타임은 _source.community_name을 읽어 [커뮤니티 이름] 메시지 prefix를 자동으로 붙입니다. RSS/Atom/JSON Feed의 _loopback_social 확장에도 동일 정보가 포함되어 구독자가 출처를 식별할 수 있습니다.

갱신 주기와 캐싱

매 6시간마다 cron (0 */6 * * * UTC) + docs/communities.json 변경 시 + 수동 dispatch.
aggregator는 별도 캐시 우회를 하지 않으므로, 운영하시는 사이트의 Cache-Control은 자유롭게 설정하셔도 됩니다 (권장: max-age=600 이내).
다음 cron 시점까지 기다리지 않고 즉시 반영하고 싶으면 운영자가 aggregate-network.yml 워크플로의 "Run workflow"를 누를 수 있습니다.

장애 동작

한 URL이 fetch 실패(타임아웃·HTTP error·1 MB 초과)하거나 스키마 검증에 실패하면 해당 URL만 스킵하고, 다른 커뮤니티는 정상 처리됩니다. 하나의 깨진 소스가 전체 수집을 막지 않습니다.
실패는 Actions 로그에 ::warning::network aggregator failures: …로 기록되며, 워크플로 실행 로그에서 사유를 확인할 수 있습니다.

항목 라이프사이클

end가 과거가 된 항목도 30일 동안 docs/news.network.json에 남아 RSS/Atom/JSON Feed 구독자가 최근 변경을 따라잡을 수 있게 합니다. 30일이 지나면 자동으로 제거됩니다.

로컬 검증

작성하신 JSON이 schema에 부합하는지 사전에 확인:

npx ajv-cli@5 validate \
  -s https://loopback.social/schemas/news.schema.json \
  -d my-news.json \
  --strict=false --all-errors

aggregator를 직접 돌려보고 싶다면:

git clone https://github.com/loopback-social/community-network-banner
cd community-network-banner
npm install --no-save ajv@8
node .github/scripts/aggregate-network.mjs
# → docs/news.network.json에 픽업 결과가 기록됨