Belajar Backstage - Search & Discovery

#Pendahuluan

Di episode 15, kalian mengamankan deployment dari jaringan hingga cookie. Episode 16 ini memanfaatkan keamanan itu untuk satu tujuan yang paling dirasakan developer: search & discovery. Masalah utama developer portal justru bukan kurangnya informasi, melainkan tersebarnya informasi — dokumentasi di satu tempat, kode di tempat lain, tim di tempat yang lain lagi. Search di Backstage menarik semua sumber itu ke satu kotak pencarian, sehingga developer menemukan entity, dokumentasi, dan konteks dalam satu query.

#Arsitektur Search di Backstage

Search di Backstage terdiri dari tiga lapisan besar:

• Backend search — mengumpulkan, memproses, dan mengindeks dokumen dari berbagai sumber.
• Search engine — menyimpan index dan mengeksekusi query (seperti yang disinggung di episode 12).
• Frontend search — kotak pencarian yang menampilkan hasil kepada user.

Lapisan-lapisan ini saling bertukar dokumen dan query lewat API terpisah, sehingga kalian bisa mengganti search engine atau menambah sumber baru tanpa menyentuh frontend.

#Indexing Pipeline: Collators, Decorators, Indexers

Proses mengindeks berjalan dalam pipeline dengan tiga peran:

1. Collators — mengambil dokumen dari sumber (collate), misalnya membaca semua entity dari catalog atau semua halaman dari TechDocs.
2. Decorators — memperkaya dokumen dengan metadata tambahan, seperti mengaitkan dokumen dengan entity pemiliknya agar hasil bisa difilter berdasarkan tim.
3. Indexers — menulis dokumen yang sudah jadi ke search engine.

search:
  backend:
    engine: postgres
    auth:
      enableProtectedResult: true

Satu collator bisa memproduksi banyak dokumen, dan beberapa collator bisa berjalan paralel. Pipeline ini berjalan di latar belakang, terus menyinkronkan index dengan perubahan di sumber.

#Menjalankan dan Memverifikasi Indexing

Pipeline indexing berjalan otomatis di backend, tetapi saat pertama kali menyiapkan search, kalian perlu memastikan collator benar-benar mengambil data:

curl -s http://localhost:7007/api/search/index -H "Authorization: Bearer ${BACKSTAGE_TOKEN}"

Responsnya menunjukkan dokumen yang sudah terindeks per collator. Jika angka ini tidak bertambah setelah data baru ditambahkan ke catalog, periksa log backend untuk error di collator atau indexer terkait. Jadwalkan juga sinkronisasi berkala — index yang basi hanya menyesatkan developer.

Jika kalian menjalankan beberapa instance backend, pastikan hanya satu instance yang menangani indexing (atau gunakan task scheduler) agar collator tidak menduplikasi pekerjaan.

#Search Types

Setiap collator menandai dokumennya dengan search type — identitas yang menentukan bagaimana hasil dirender dan difilter. Tipe bawaan yang umum antara lain software-catalog untuk entity, techdocs untuk dokumentasi, dan tipe dari collator lain untuk sumber masing-masing. Saat frontend menerima hasil, tipe ini dipakai untuk memilih tampilan yang tepat — hasil entity menampilkan jenis dan owner, hasil TechDocs menampilkan jalur dokumentasi.

#Query API

Frontend berkomunikasi dengan backend search lewat query API. Query menggabungkan istilah pencarian, filter tipe, dan opsi pagination, lalu backend search meneruskannya ke engine dan mengembalikan hasil yang sudah diberi skor. URL relatif yang dipakai adalah /api/search/query — memanggilnya dari plugin frontend adalah satu pemanggilan yang sama untuk semua jenis sumber, sehingga pengalaman pencarian tetap seragam.

Dari sisi keamanan, ingat pelajaran episode 15: hasil pencarian bisa berisi informasi sensitif, jadi pastikan hasil yang dilindungi tidak bocor ke user yang tidak berhak. Backstage menyediakan mekanisme hasil terlindungi yang memfilter dokumen berdasarkan permission — aktifkan fitur ini sebelum search dipakai secara luas.

#Perbandingan Search Providers

Provider resmi tersedia sebagai modul search backend, misalnya untuk Stack Overflow dan GitHub issues. Yang penting: setiap provider hanya perlu collator dan indexer — engine dan query API dipakai bersama.

#Custom Collator

Saat sumber tidak punya provider resmi, kalian menulis custom collator — fungsi yang menghasilkan dokumen search dari sumber apa pun yang bisa diakses Backstage. Modul collator didaftarkan di @backstage/plugin-search-backend-node:

const myCollator = {
  async execute() {
    const documents = [];
    const services = await myInternalApi.listServices();
    for (const service of services) {
      documents.push({
        title: service.name,
        text: service.description,
        location: `/service/${service.slug}`,
        metadata: { owner: service.owner },
      });
    }
    return documents;
  },
};

Dokumen yang dihasilkan lalu didaftarkan sebagai tipe search baru dan diindeks lewat indexer yang sama. Dengan pola ini, collator apa pun — dari registry internal sampai wiki perusahaan — bisa masuk ke satu kotak pencarian Backstage.

#Penutup

Episode 16 ini menghadirkan search & discovery: arsitektur tiga lapis, pipeline indexing dengan collators, decorators, dan indexers, search types untuk kontrol rendering dan filter, query API yang seragam, provider bawaan untuk catalog, TechDocs, Stack Overflow, dan GitHub issues, serta custom collator untuk sumber internal.

Inti yang harus dibawa pulang:

• Collator memproduksi, decorator memperkaya, indexer menyimpan — tiga peran dalam satu pipeline.
• Search type menentukan pengalaman hasil — bukan hanya filter, tetapi juga cara render.
• Satu query API untuk semua sumber — frontend tidak peduli asal dokumen.
• Custom collator membuka sumber apa pun — dari internal registry sampai wiki.

Di episode 17 berikutnya, kalian masuk ke Fase 5: frontend plugin development — bagaimana membangun plugin dengan New Frontend System, dari createFrontendPlugin dan extension points sampai React hooks seperti useEntity dengan styling MUI.