JSX

Wypada jednak na samym początku wspomnieć, czym w ogóle jest JSX. Za oficjalną dokumentacją:

JSX is an XML-like syntax extension to ECMAScript without any defined semantics. […] It's intended to be used by various preprocessors (transpilers) to transform these tokens into standard ECMAScript.

[JSX to rozszerzenie składni ECMAScript o składnię podobną do XML-a bez definiowania konkretnej semantyki. […] Jest przeznaczone do użytku przez różnego rodzaju preprocesory (transpilery) do transformacji tych tokenów w standardową składnię ECMAScriptu.]

Przekładając to na ludzki – JSX pozwala umieszczać w kodzie JS coś, co wygląda jak kod XML:

const component = <article>
	<h1>Hello, world!</h1>
	<p>Some content</p>
</article>;

Niemniej kod w takiej postaci nie ma być rozumiany przez przeglądarki czy środowiska uruchomieniowe typu Node.js. Taki kod powinien być najpierw przepuszczony przez jakieś narzędzie (transpiler), które przetłumaczy go na zwyczajny kod JS. Praktycznie każdy szanujący się transpiler JS-a ma wsparcie dla JSX-a (np. TypeScript ma wbudowane, a Babel potrzebuje pluginu). Jeśli przepuścimy przez jeden z nich powyższy kod, powinniśmy otrzymać coś takiego:

const component = React.createElement( 'article', null, // 1
	React.createElement( 'h1', null, 'Hello, world!' ), // 2
	React.createElement( 'p', null, 'Some content' ) // 3
);

Każdy z XML-owych elementów w naszym JSX-ie został zamieniony na wywołanie funkcji React.createElement(). Jest też oddana relacja między poszczególnymi elementami – wywołania dla h1 (2) i p (3) znajdują się wewnątrz wywołania dla article (1). Dzięki temu React jest w stanie odtworzyć w swoim vDOM-ie dokładnie takie drzewko, jakie zaprojektowaliśmy w JSX-ie.

Wykorzystanie własnej funkcji

Domyślnie JSX jest zawsze tłumaczony do wywołań funkcji React.createElement(). A co jeśli nie chcemy korzystać z Reacta? Wówczas mamy dwie możliwości podmiany tej funkcji.

Pierwsza z nich, mniej elegancka, to… stworzenie funkcji React.createElement():

const React = {
	createElement() {
		// Tutaj jakiś kod
    }
};

Niemniej istnieje też bardziej elegancka metoda: nadpisanie semantyki JSX-a. Czyli powiedzenie naszemu transpilerowi, jak dokładnie ma transformować kod JSX. Minusem tej metody jest różnica w konfiguracji poszczególnych narzędzi. W przypadku jednak tych najpopularniejszych (TypeScript, Babel, esbuild) można wykorzystać pragmę – czyli komentarz wskazujący odpowiednią funkcję:

/* @jsx myFunction */
const component = <article>
	<h1>Hello, world!</h1>
	<p>Some content</p>
</article>;

W tym przypadku informujemy transpiler, że ma używać funkcji o nazwie myFunction(). Dzięki temu po transpilacji dostaniemy następujący kod:

/* @jsx myFunction */
const component = myFunction( 'article', null,
	myFunction( 'h1', null, 'Hello, world!' ),
	myFunction( 'p', null, 'Some content' )
);

Dzięki temu możemy podstawić naszą implementację React.createElement(), która czekała na ten moment niemalże 9 lat:

Ale wypluwanie elementów HTML z JSX-a jest nudne. Tak naprawdę można generować absolutnie wszystko, co da się zapisać jako drzewko elementów. Jak np. tekstowe drzewko plików:

W tym przypadku funkcja obsługująca JSX wygląda następująco:

function jsx( tag, attributes, ...children ) {
	const { name } = attributes; // 1

	const childrenContent = children.map( ( child ) => {
		return `${ child }`
			.replaceAll( /^/gm, '\n|   ' ) // 3
			.replaceAll( '\n\n', '\n' );
	} ).join( '' ); // 4

	return `| - ${ name }${ childrenContent }`;
}

Z JSX-owego elementu pobieramy atrybut name (1) – to nazwa katalogu lub pliku. Zwracamy ją (2) jako ciąg tekstowy razem z fajką (|), wskazującą aktualny poziom zagłębienia, oraz ciągami tekstowymi zwróconymi przez dzieci. Te nieco modyfikujemy, dodając do każdego pliku/katalogu brakujące fajki (3), a następnie łącząc wszystkie dzieci w jeden duży ciąg tekstowy (4).

Natomiast JSX użyty do tego przykładu wygląda następująco:

/* @jsx jsx */
const component = <directory name="/">
	<file name="README.md" />
	<directory name="src/">
		<file name="index.ts" />
	</directory>
</directory>;

Komponenty

Niemniej w JSX-ie oprócz zwyczajnych elementów istnieją również komponenty, a więc elementy, których nazwy zaczynają się wielką literą. Spójrzmy na taki przykład:

const component = <Greeting name="Comandeer" />;

Jeśli przepuścimy ten kod przez transpiler, otrzymamy mniej więcej coś takiego:

const component = React.createElement( Greeting, { name: 'Comandeer' } );

W tym przypadku do React.createElement() jako pierwszy argument nie jest przekazywana nazwa elementu, ale referencja do Greeting. Wypada zatem stworzyć taką funkcję:

function Greeting( { name } ) { // 1
	return <h1>Hello, {name}!</h1>; // 2
}

Jako parametr przyjmuje ona obiekt z atrybutami (1), z którego wyciągamy atrybut name. Następnie zwracamy element h1, wewnątrz którego wykorzystujemy ten atrybut do stworzenia powitania (2).

Wypada nieco zmodyfikować naszą funkcję do obsługi JSX-a:

function jsx( tag, attributes, ...children ) {
	if ( typeof tag === 'function' ) { // 1
		return tag( { ...attributes, children } ); // 2
	}

	const element = document.createElement( tag );

	if ( attributes && typeof attributes === 'object' ) {
		Object.entries( attributes ).forEach( ( [ name, value ] ) => {
			element.setAttribute( name, value );
		} );
	}

	children.forEach( ( child ) => {
		element.append( child ); // 3
	} );

	return element;
}

Większość logiki została taka sama, pojawił się jedynie dodatkowy warunek na początku. Sprawdza on, czy przekazany tag jest funkcją (1) i jeśli tak, to wywołuje ją, przekazując jako parametr obiekt zawierający atrybuty oraz własność children z dziećmi (2). Robimy to w taki sposób, żeby zachować Reactowy kształt API. Przy okazji, dzięki użyciu metody #append() (3) przy dodawaniu dzieci zniknęła potrzeba tworzenia węzła tekstowego. Metoda #append() bowiem, w przeciwieństwie do starszej metody #appendChild(), pozwala dodawać tekst bezpośrednio do elementu.

Nasza obsługa komponentów prezentuje się następująco:

I tak oto udało nam się przygotować własną, prostą obsługę JSX-a! Oczywiście, nie jest ona skończona, brakuje choćby sensownej obsługi fragmentów. Niemniej jest fajnym punktem wyjścia do dalszych eksperymentów.

Kanały Atom

Dawno, dawno temu ktoś wpadł na szalony pomysł: a co jeśliby pozwolić ludziom czytać treść ze stron internetowych jak i kiedy chcą? Zamiast musieć wchodzić na konkretną stronę WWW, ktoś mógłby po prostu dostać informację o nowym wpisie na blogu czy zdjęciu w galerii podobnie, jak dostaje maila. Ot, taki newsletter, tylko że nie przez maila. Tak powstały tzw. feeds (kanały). W największym skrócie: kanał to plik w formacie innym niż HTML, w którym znajduje się treść strony i który jest przystosowany do czytania przez tzw. feed readers (czytniki kanałów). Te czytniki pobierają kanały ze stron co pewien czas, by sprawdzić, czy na stronie pojawiło się coś nowego. Osobiście używam ich jako głównego sposobu na dowiadywanie się o nowościach ze światka webdevu.

Obecnie mamy trzy standardy kanałów: Really Simple Syndication (RSS), Atom oraz JSON Feed. Te dwa pierwsze to formaty oparte o XML, podczas gdy ostatni, jak sama nazwa sugeruje, o JSON. Na tym blogu stosuję format Atom.

Problemy z kanałem

Przy okazji odświeżenia bloga dodałem też do nagłówków w postach linki odsyłające do konkretnych sekcji:

<h2 id="odświeżone-bloczki"> <!-- 2 -->
	<a class="header-anchor" href="#odświeżone-bloczki">Odświeżone bloczki</a> <!-- 1 -->
</h2>

Zawartość nagłówka jest otoczona linkiem (1), który odsyła do tego nagłówka przy pomocy kotwicy (2). Problem polega na tym, że atrybut [href] zawiera samą nazwę kotwicy, nie cały URL. A to sprawia, że gdy taki link zostanie wyciągnięty poza oryginalny kontekst (np. do czytnika kanałów), linki w nagłówkach przestają działać. I od dłuższego czasu odkładałem poprawienie tego na później, aż w końcu…

…aż w końcu zmieniłem też bloczki kodu i do problemu z nagłówkami doszedł kolejny:

Z racji tego, że czytnik kanałów wycina potencjalnie niebezpieczne elementy, przycisk do kopiowania zawartości bloczków kodu zamienił się w zwykły tekst. Co więcej, nawet gdyby mój czytnik zostawił w tym miejscu przycisk, to i tak by on nie zadziałał, bo nie ma sposobu na dodanie JS-a do kanału Atom. Innymi słowy: kanał mojego bloga miał już dwa niedziałające elementy. Przyszła pora, by coś z tym zrobić!

Naprawa HTML-a

Postanowiłem dodać filtr w Eleventy, który brałby treść posta i wycinał z niego wszystkie elementy, które nie działają w kanale. Problem polega jednak na tym, że w momencie stosowania filtru zawartość posta jest już sparsowana z Markdowna do HTML-a. A to oznacza, że muszę parsować HTML. W tym celu postanowiłem użyć biblioteki cheerio, która dostarcza API podobnego do jQuery. Ostatecznie powstał następujący filtr:

import { load } from 'cheerio'; // 2

const MORE_COMMENT_REGEX = /<!--\s*more\s*-->/; // 10

eleventyConfig.addFilter( 'rss_content', ( post ) => { // 1
	const postURL = cfUrl( new URL( post.data.permalink, post.data.site.url ).href ); // 7
	const $ = load( post.content ); // 3

	$( ':where(h1, h2, h3, h4, h5, h6) a' ).each( ( _, link ) => { // 4
		const $link = $( link );
		const originalHref = $link.attr( 'href' ); // 5

		$link.attr( 'href', postURL + originalHref ); // 6
	} );
	$( '.code__copy' ).remove();

	return $( 'body' ).html().replace( MORE_COMMENT_REGEX, '' ); // 9
} );

Dodajemy nowy filtr o nazwie rss_content (1). Przekazujemy mu obiekt wpisu. Następnie importujemy funkcję load() z biblioteki cheerio (2). Pozwala ona sparsować kod HTML do DOM-u. Używamy jej do sparsowania zawartości postu (3). Na tak stworzonym drzewku wyszukujemy wszystkie linki w naglówkach (4) i dla każdego z nich pobieramy wartość atrybutu [href] (5) oraz zamieniamy go na absolutny URL (6) – a więc #odświeżone-bloczki zamienią się na https://blog.comandeer.pl/inkunabuly-madrosci#odświeżone-bloczki. Absolutny URL uzyskujemy, sklejając link do posta z linkiem do strony przy pomocy konstruktora URL (7). Link do posta jest dostarczony przez Eleventy, natomiast link do strony – przeze mnie przy pomocy mechanizmu globalnych plików z danymi. Po naprawieniu linków, wyszukujemy i usuwamy wszystkie przyciski do kopiowania kodu (8). Na koniec wyciągamy kod HTML z DOM-u i usuwamy z niego komentarz <!--more--> (9) przy pomocy wyrażenia regularnego (10). Mimo usilnych starań nie udało mi się usunąć go w bardziej przyzwoity sposób, używając API biblioteki cheerio. Warto tutaj zwrócić uwagę, że kod HTML wyciągamy z elementu body. Biblioteka cheerio parsuje bowiem HTML zgodnie z regułami opisanymi w specyfikacji, a więc – jako pełny dokument, co sprawia, że dodaje brakujące elementy html i body. Można też wymusić na cheerio parsowanie w trybie fragmentu, podając false jako trzeci argument do funkcji load().

Tajemnicza funkcja cfUrl() z poprzedniego fragmentu kodu wycina z przekazanego linku rozszerzenie .html lub fragment index.html:

function cfUrl( url ) {
	return url.replace( /index\.html$/, '' ).replace( /\.html$/, '' );
}

Dzięki temu linki typu /blog-2.0.html lub /kategorie/javascript/index.html zmienią się odpowiednio w /blog-2.0 oraz /kategorie/javascript.

Tak stworzony filtr dodajemy następnie do szablonu kanałów, w miejscu, w którym wyświetlana jest treść posta:

<content type="html"><![CDATA[{{ post | rss_content }}]]></content>

I to w sumie tyle! W końcu kanały bloga powinny działać poprawnie.

Stare bloczki

Stare bloczki… były:

Co prawda spełniały swoje zadanie, miały nawet dobre kolorowanie składni (dzięki Shiki), ale brakowało w nich choćby informacji o języku programowania. Dlatego też postanowiłem je nieco odświeżyc.

Odświeżone bloczki

Nowe bloczki wyglądają następująco:

Tak naprawdę zmiany nie są szczególnie wielkie – pojawiła się jedynie nazwa języka oraz przycisk do skopiowania kodu do schowka.

Nowy HTML

Od strony HTML-a cały bloczek kodu trafił do elementu figure:

<figure class="code" typeof="SoftwareSourceCode">
	<figcaption class="code__caption"> <!-- 3 -->
		<span class="code__title" property="programmingLanguage">CSS</span> <!-- 1 -->
		<button class="code__copy">Kopiuj</button> <!-- 2 -->
	</figcaption>
	<div class="code__code" translate="no" property="text"> <!-- 4 -->
		<pre><code>[…]</code></pre> <!-- 5 -->
	</div>
</figure>

Podpis z nazwą języka (1) i przyciskiem (2) został umieszczony w figcaption (3), natomiast sam kod w dodatkowym divie z atrybutem [translate=no] (4). Dzięki temu Google Translate i podobne usługi nie będą próbowały tłumaczyć kodu na inne języki. Dodatkowo zastosowałem też RDFa, żeby oznaczyć całość jako kod w języku programowania. Sam kod (5) pozostał bez zmian – dalej jest kolorowany przez Shiki.

Nowy JS

Przycisk do kopiowania kodu potrzebuje obsługi w JS-ie. Dodałem więc taką do swojego pliku JS:

document.addEventListener( 'click', async ( evt ) => { // 1
	const isCopyButton = evt.target.closest( '.code__copy' ); // 2

	if ( !isCopyButton ) {
		return;
	}

	const closestCode = evt.target.closest( '.code' ).querySelector( '.code__code' ); // 3

	await navigator.clipboard.writeText( closestCode.innerText ); // 4
} );

Stosuje tutaj technikę event delegation (delegacji zdarzeń) (1). Dzięki temu mogę przypiąć tylko jeden nasłuchiwacz i obsłużyć wszystkie przyciski “Kopiuj”, zamiast musieć się przypiąć do każdego z nich osobno. Niemniej ta technika sprawia, ze muszę sprawdzić, czy na pewno został kliknięty przycisk “Kopiuj”. Robię to przy pomocy wyszukania go przez metodę #closest() (2). Metoda ta zwróci najbliższy element o klasie .code__copy. W przypadku, gdy ktoś kliknie przycisk, będzie to on sam. Metoda #closest() zabezpiecza nas przed przypadkiem, gdybyśmy dodali kiedyś ikonkę do przycisku i ktoś kliknął w nią – wówczas zamiast przycisku mielibyśmy w evt.target np. element svg. Jak już ustalimy, że został naciśnięty odpowiedni przycisk, wyszukujemy najbliższy bloczek kodu (3). Następnie wywołujemy metodę Clipboard#writeText(), do której przekazujemy tekstową zawartość bloczka (4). Jeśli osoba naciskająca przycisk wyrazi zgodę na zapisanie danych do schowka, kod zostanie skopiowany.

Nowy backend

Nowe bloczki kodu renderowane są przy pomocy autorskiego pluginu do MarkdownIt (biblioteki renderującej Markdowna w Eleventy). Jego kod prezentuje się następująco:

function markdownItCodeBlock( markdownIt ) {
	const originalFenceRule = markdownIt.renderer.rules.fence; // 1

	markdownIt.renderer.rules.fence = ( tokens, idx, options, env, slf ) => {
		const token = tokens[ idx ];
		const lang = token.info ? token.info.trim() : ''; // 3
		const renderedCodeBlock = originalFenceRule( tokens, idx, options, env, slf ); // 4

		/ * 5 */ return `<figure class="code" typeof="SoftwareSourceCode">
			<figcaption class="code__caption">
				<span class="code__title" property="programmingLanguage">${ langs[ lang ] ?? '' }</span>
				<button class="code__copy">Kopiuj</button>
			</figcaption>
			<div class="code__code" translate="no" property="text">
				${ renderedCodeBlock }
			</div>
		</figure>`;
	};
}

Na początku zapisujemy sobie do zmiennej aktualną funkcję do renderowania bloczków kodu (1). W przypadku MarkdownIt funkcja ta znajduje się w regułach renderera. Następnie nadpisujemy tę regułę własną (2). Wyciągamy z kodu Markdown nazwę języka programowania (3), a następnie wywołujemy oryginalną regułę renderującą bloczki kodu (4). Dzięki temu dostajemy kod ładnie pokolorowany przez Shiki. Na koniec tworzymy nasz własny kod HTML bloczka (5), do którego wsadzamy pokolorowany kod i zwracamy całość z funkcji.

Teraz zostaje tylko dodać ten plugin do naszej zmodyfikowanej wersji MarkdownIt. Można to zrobić przy pomocy metody #use().

I to tyle! Bloczki kodu na blogu są od teraz nieco lepsze.

Problem z istniejącymi aplikacjami

Żeby zabezpieczyć aplikację przy pomocy HTML Sanitizer API, trzeba zadbać o to, żeby wszystkie miejsca, w których dodajemy HTML, korzystały z nowej metody #setHTML(). Innymi słowy: wszystkie wystąpienia własności #innerHTML trzeba podmienić. I choć na pierwszy rzut oka nie wydaje się to specjalnie skomplikowane, to z powodu złożoności aplikacji może to nastręczyć sporo problemów.

Pierwszym z nich jest zmiana zachowania aplikacji. Dotąd HTML był ustawiany bez dodatkowego czyszczenia. Teraz jest filtrowany. W zależności od aplikacji, może to być problemem. Weźmy takiego CKEditora. Jeśli nagle przestanie działać dodawanie obrazków w edytorze (bo HTML Sanitizer APi je wytnie), to on sam stanie się średnio użyteczny. Stąd proste podmienienie własności #innerHTML na metodę #setHTML() w takim wypadku nie zadziała.

Drugi z problemów związany jest z samym refactorem. Bo to prawie nigdy nie jest po prostu podmiana czegoś w kodzie. Często trzeba też zmienić choćby testy, które mogą zacząć padać po zmianie zachowania aplikacji. Często też trzeba sprawdzić, czemu testy nie zaczęły padać – by się upewnić, że na pewno wszystko dobrze testują.

Trzeci problem to zależności aplikacji. Nasz kod możemy w ten czy inny sposób zrefactoryzować. Ale z zależnościami nie jest już tak łatwo i najczęściej kończy się na czekaniu, aż dany projekt doda wsparcie dla nowego API. A na to se można poczekać – o ile dany projekt w ogóle będzie chciał taką zmianę wprowadzić.

I wreszcie: kompatybilność. Dopóki HTML Sanitizer API nie będzie miało sensownego wsparcia we wszystkich najważniejszych przeglądarkach, trzeba będzie zadbać o alternatywę. Najprawdopodobniej w postaci polyfilla. A to dodatkowo niepotrzebnie skomplikuje kod i dołoży kolejną zależność do projektu.

Innymi słowy: wdrożenie HTML Sanitizer API może być sporym wyzwaniem w istniejących projektach.

Trusted Types API

Na szczęście istnieje inne API, które ma zdecydowanie lepsze wsparcie i które można wpiąć w już istniejące aplikacje przy minimalnej ingerencji. To API to Trusted Types API (API Zaufanych Typów). Pozwala ono zabezpieczyć tzw. injection sinks (miejsca wstrzykiwania) przy pomocy polityk.

Miejsca wstrzykiwania

Miejsca wstrzykiwania to wszystkie te fragmenty kodu, w których do strony WWW jest dodawana treść lub może być wykonany skrypt JS. Najprostszym przykładem jest własność #innerHTML, przy pomocy której można wsadzić HTML do wybranego elementu. Są też jednak mniej oczywiste przykłady:

• własność HTMLScriptElement#text – służąca do zmiany zawartości elementu script,
• własność HTMLScriptElement#src – służąca do zmiany źródła elementu script,
• funkcja eval() – wykonująca przekazany jej kod JS,
• metoda DOMParser#parseFromString() – parsująca przekazany kod HTML,
• metoda setHTMLUnsafe() – służąca do zmiany zawartości elementu z pominięciem czyszczenia przekazanego kodu.

Takie przykłady można by mnożyć. MDN zawiera sporą listę potencjalnych miejsc wstrzykiwania.

Polityki

Trzonem Trusted Types API są tzw. polityki. To obiekty zawierające konfigurację opisują, w jaki sposób mają być zabezpieczone poszczególne miejsca wstrzykiwania. Każda polityka może składać się z trzech metod-fabryk:

• #createHTML() – służąca do tworzenia obiektów TrustedHTML, które mogą być później używane wszędzie tam, gdzie trzeba przekazać kod HTML, np. własność #innerHTML lub metoda #setHTMLUnsafe(),
• #createScript() – służąca do tworzenia obiektów TrustedScript, które mogą być później używane tam, gdzie jest potrzebny kod JS, np. wewnątrz funkcji eval(),
• #createScriptURL() – służąca do tworzenia obiektów TrustedScriptURL, które mogą być później używane tam, gdzie potrzebny jest adres skryptu JS, np. we własności HTMLScriptElement#src.

Żeby dodać nową politykę, trzeba skorzystać z metody trustedTypes#createPolicy():

const policy = trustedTypes.createPolicy( 'my-policy', { // 1
	createHTML( html ) { // 2
		return sanitizeHTML( html );
	},

	createScript( js ) { // 3
		return sanitizeJS( js );
	},

	createScriptURL( url ) { // 4
		return sanitizeURL( url );
	}
} );

Tworzymy nową politykę o nazwie my-policy i zapisujemy ją do zmiennej policy (1). Ma ona wszystkie trzy metody – #createHTML() (2), #createScript() (3) oraz #createScriptURL() (4). Zwracają one przekazany im kod przepuszczony przez odpowiednie funkcje filtrujące (5, 6, 7 ). To, co te funkcje robią, zależy w zupełności od nas. W końcu każda aplikacja jest inna i może mieć inne wymagania odnośnie czyszczenia HTML-a czy JS-a. Na potrzeby przykładu stwórzmy zaślepki, które po prostu zwrócą przekazany im argument:

function sanitizeHTML( html ) {
	return html;
}

function sanitizeJS( js ) {
	return js;
}

function sanitizeURL( url ) {
	return url;
}

Żeby wykorzystać w praktyce naszą politykę, trzeba wywołać jej metody:

const div = document.createElement( 'div' ); // 1

div.innerHTML = policy.createHTML( '<p>Jestem zaufanym HTML-em</p>' ); // 2

eval( policy.createScript( 'alert(1)' ) ); // 3

const script = document.createElement( 'script' ); // 4

script.src = policy.createScriptURL( 'data:text/javascript;charset=utf-8;base64,YWxlcnQoMSk=' ); // 5

Tworzymy element div (1), a następnie wsadzamy do niego “zaufany” HTML, stworzony przy pomocy metody policy#createHTML() (2). Z kolei do funkcji eval() przekazujemy “zaufany” skrypt, stworzony przy pomocy metody policy#createScript() (3). Na koniec tworzymy element script (4) i ustawiamy jego własność #src na “zaufany” URL skryptu stworzony przy pomocy metody policy#createScriptURL() (5).

Wymuszanie polityki

Samo jednak dodanie polityki nie zabezpieczy aplikacji. Przeglądarka nie będzie miała żadnego problemu z tym, żeby ją ominąć i ustawić własność #innerHTML na dowolny tekst. Dlatego API dostarcza też mechanizm, który wymusza stosowanie polityki. Służy do tego dyrektywa require-trusted-types-for w nagłówku HTTP Content-Security-Policy:

Content-Security-Policy: require-trusted-types-for 'script';

Jak na razie jedyną wartością dla tej dyrektywy jest 'script', która pokrywa wszystkie trzy przypadki (kod HTML, kod JS i URL-e skryptów).

Jeśli wyślemy taki nagłówek HTTP, a następnie spróbujemy wstawić niezabezpieczony tekst do własności #innerHTML, powinniśmy otrzymać następujący błąd:

This document requires 'TrustedHTML' assignment. The action has been blocked.

Istnieje też dyrektywa trusted-types, która kontroluje tworzenie polityk:

Content-Security-Policy: require-trusted-types-for 'script';trusted-types my-policy;

Taki nagłówek wymusi używanie polityki, a równocześnie pozwoli stworzyć jedynie taką o nazwie my-policy.

Domyślna polityka

Ale zaraz, zaraz – czy to API nie miało być tym “mniej inwazyjnym”, które nie wymaga sporego refactoru istniejących aplikacji? Takie tworzenie polityk wydaje się wręcz jeszcze bardziej upierdliwe, niż prosta zamiana #innerHTML na #setHTML(). Na całe szczęście Trusted Types API ma asa w rękawie: domyślną politykę. Jeśli wymusimy stosowanie polityk przy pomocy dyrektywy require-trusted-types-for, a następnie stworzymy politykę o nazwie default, będzie ona automatycznie wykorzystywana w każdym miejscu wstrzykiwania:

trustedTypes.createPolicy( 'default', { // 1
	createHTML( html ) {
		console.log( 'HTML' ); // 5

		return html; // 2
	},

	createScript( js ) {
		console.log( 'JS' ); // 6

		return js; // 3
	},

	createScriptURL( url ) {
		console.log( 'URL' ); // 7

		return url; // 4
	}
} );

Tworzymy nową politykę o nazwie 'default' (1). Ponownie tworzymy metody-fabryki, w których zwracamy przekazany im kod (2, 3, 4). Wcześniej jednak logujemy w konsoli, jaki typ danych filtrujemy (5, 6, 7)

Wykorzystanie tej polityki jest całkowicie przezroczyste:

const div = document.createElement( 'div' );

div.innerHTML = '<p>Jestem zaufanym HTML-em</p>'; // 1

eval( 'alert(1)' ); // 2

const script = document.createElement( 'script' );

script.src = 'data:text/javascript;charset=utf-8;base64,YWxlcnQoMSk='; // 3

Nie trzeba się już odwoływać do polityki ani przy przypisywaniu wartości do własności #innerHTML (1), ani przy wywoływaniu funkcji eval() (2), ani przy ustawianiu źródła skryptu (3).

Jeśli odpalimy ten kod w przeglądarce, wówczas powinniśmy zobaczyć w konsoli logi potwierdzające, że polityka została zaaplikowana do każdego z trzech miejsc wstrzykiwania.

Kompatybilność

Specyfikacja Trusted Types API jest już na dość zaawansowanym etapie standaryzacji. Choć wciąż może się zmieniać, nie oczekiwałbym jakichś wielkich, wywrotowych zmian. Jak już jakieś nastąpią, to raczej kosmetyczne. Natomiast wsparcie jest już od dłuższego czasu zarówno w Chrome, jak i w Safari. W Firefoksie wciąż jest eksperymentalne za flagą.

Myślę, że dopóki wsparcie nie będzie we wszystkich najważniejszych przeglądarkach, najlepiej się ograniczyć do tworzenia domyślnej polityki i wymuszać ją przy pomocy dyrektywy require-trusted-types-for. Dzięki temu całość będzie jak najbardziej transparentna dla przeglądarek, które wciąż nie wspierają tego API. Natomiast cała reszta dostanie lepsze zabezpieczenie przed atakami XSS.

I w końcu będzie można zacząć ufać własności #innerHTML!

XSS – czyli co zagraża aplikacji WWW?

Zacznijmy od tego, czym w ogóle jest atak Cross-Site Scripting (XSS). W największym skrócie: to atak polegający na wstrzyknięciu złośliwego kodu na stronę WWW. Ten kod następnie zostanie wykonany przez przeglądarkę osoby odwiedzającej stronę. Taki kod może zrobić tak naprawdę wszystko, co potrafi JS w przeglądarce, np. pobranie ciasteczek i wysłanie ich do zewnętrznego serwera.

Wstrzyknięcia można dokonać na wiele różnych sposobów. Jednym z najczęstszych jest wykorzystanie formularzy na stronie, np. edytora postów na blogu czy księgi gości. Jeśli dostęp do takiego formularza mają też niezaufane osoby, wówczas jest spora szansa, że jedna z nich spróbuje zaatakować stronę. Choćby zostawiając poniższy wpis:

<img src="x" onerror="alert( 'Słaba ta strona!' )">

Jeśli w żaden sposób nie filtrujemy danych przychodzących, tego typu kod może trafić do bazy danych, a ostatecznie – do przeglądarek innych osób odwiedzających stronę. Każdej z tych osób pokaże się wówczas wyskakujące okienko z tekstem Słaba ta strona!. Dzieje się tak, ponieważ atrybut [onerror] dodaje do obrazka nasłuchiwacz dla zdarzenia error. A to odpala się m.in wówczas, gdy wczytywany obrazek nie istnieje. Jeśli nie mamy na stronie obrazka pod ścieżką /x (a mało kto ma), to zdarzenie się odpali i kod wykona się u niczego niepodejrzewających osób odwiedzających naszą stronę.

Istniejące sposoby ochrony

Mimo że XSS to jeden z podstawowych typów ataków, niemal tak stary jak sam Internet, to wciąż jest niezwykle popularny. Wciąż mocno się trzyma na liście Top 10 OWASP – raporcie opisującym dziesięć najpopularniejszych typów ataków w Internecie. Dlatego też wciąż potrzeba sensownych i sprawdzonych metod obrony przed nim. Dotąd trzeba było wykorzystywać w tym celu różne biblioteki. Jedną z najpopularniejszych jest DOMPurify, które działa nie tylko w przeglądarce, ale także w Node.js. Działanie tej biblioteki można zobaczyć w oficjalnym demie. Polega na usuwaniu z przekazanego ciągu tekstowego wszystkich niebezpiecznych fragmentów HTML-a. Jako przykład posłuży nam następujący kod:

<script>alert( 'script' );</script> <!-- 1 -->
<img src="x" alt="" onerror="alert('obrazek')"> <!-- 2 -->
<span onmouseover="alert('hover')">Najedź mnie</span> <!-- 3 -->

Powyższy kod HTML po odpaleniu w przeglądarce wyświetli trzy wyskakujące okienka:

1. po wykonaniu skryptu z elementu script,
2. po błędzie wczytywania obrazka,
3. po najechaniu na tekst Najedź mnie.

Po przepuszczeniu tego kodu przez DOMPurify dostaniemy:

<img src="x" alt=""> 
<span>Najedź mnie</span> 

Wszystkie JS-owe elementy kodu zostały usunięte, tym samym zostawiając wyłącznie bezpieczny HTML.

HTML Sanitizer API – nowy obrońca Sieci

W końcu doczekaliśmy się API chroniącego przed XSS-em, które jest wbudowane w przeglądarkę – HTML Sanitizer API (API Dezynfekujące HTML-a). Składają się na niego dwa główne elementy:

1. metoda #setHTML(), dołączona do elementów HTML i korzeni Shadow DOM,
2. statyczna metoda Document.parseHTML().

Bezpieczny zaułek

Metoda #setHTML() jest odpowiednikiem własności #innerHTML. Główna różnica między nimi polega na tym, że nowa metoda wyrzuca z przekazanego jej kodu HTML wszystkie niebezpieczne elementy:

document.body.setHTML( `<script>alert( 'script' );</script>
<img src="x" alt="" onerror="alert('obrazek')">
<span onmouseover="alert('hover')">Najedź mnie</span>` );

Wykonanie tego kodu sprawi, że zawartość strony zostanie podmieniona na następującą:

<span>Najedź mnie</span>

Jak widać, natywne API jest nawet dokładniejsze niż domyślne ustawienia biblioteki DOMPurify. Zniknął bowiem cały element img. Gdy przyjrzymy się algorytmowi dezynfekcji HTML-a w specyfikacji, zauważymy, że jednym z kroków jest usuwanie elementów, które nie występują w konfiguracji dezynfekcji. Jeśli nie podamy własnego obiektu z opcjami, wówczas zostanie użyty domyślny – a ten nie zawiera elementu img. Stąd nie ma go też w wynikowym HTML-u. Teoretycznie, żeby zachować obrazek, jako drugi argument metody #setHTML() trzeba podać obiekt konfiguracyjny – ale na ten moment nie działa to w żadnej przeglądarce.

Z kolei metoda statyczna Document.parseHTML() jest odpowiednikiem wbudowanego parsera HTML. Metoda parsuje kod HTML, czyści go ze wszystkich niebezpiecznych fragmentów, a następnie tworzy nowy obiekt Document na jego podstawie:

console.log( Document.parseHTML( `<!DOCTYPE html>
    <html lang="pl">
        <head>
            <title>Testowy dokument</title>
        </head>
        <body>
            <script>alert( 'script' );</script>
            <h1>Hello, world!</h1>
        </body>
    </html>`) );

Ten kod wyświetli w konsoli następujący dokument:

<!DOCTYPE html>
<html lang="pl">
	<head>
		<title>Testowy dokument</title>
	</head>
	<body>
		<h1>Hello, world!</h1>
	</body>
</html>

Jak widać, dokument jest praktycznie identyczny jak ten, który przekazaliśmy metodzie Document.parseHTML(). Jedyną różnicą jest brak elementu script.

Niebezpieczna manipulacja

Warto wspomnieć, że zarówno #setHTML(), jak i Document.parseHTML(), mają swoje “niebezpieczne” odpowiedniki – #setHTMLUnsafe() oraz Document.parseHTMLUnsafe(). Działają tak samo, ale nie usuwają niczego.

Tym samym, jeśli użyjemy #setHTMLUnsafe() na naszym testowym kodzie HTML:

document.body.setHTMLUnsafe( `<script>alert( 'script' );</script>
<img src="x" alt="" onerror="alert('obrazek')">
<span onmouseover="alert('hover')">Najedź mnie</span>` );

do zawartości strony trafi dokładnie ten kod HTML, bez żadnego czyszczenia:

<script>alert( 'script' );</script>
<img src="x" alt="" onerror="alert('obrazek')">
<span onmouseover="alert('hover')">Najedź mnie</span>

Podobnie stanie się, jeśli podmienimy Document.parseHTML() na Document.parseHTMLUnsafe():

console.log( Document.parseHTMLUnsafe( `<!DOCTYPE html>
    <html lang="pl">
        <head>
            <title>Testowy dokument</title>
        </head>
        <body>
            <script>alert( 'script' );</script>
            <h1>Hello, world!</h1>
        </body>
    </html>`) );

Ten kod stworzy dokładnie taki dokument HTML:

<!DOCTYPE html>
<html lang="pl">
	<head>
		<title>Testowy dokument</title>
	</head>
	<body>
		<script>alert( 'script' );</script>
		<h1>Hello, world!</h1>
	</body>
</html>

Kompatybilność

Gdzie zatem można użyć nowego API? Otóż… nigdzie. Pojawić się powinno w Firefoksie 147, którego wydanie planowane jest na 13 stycznia 2026 roku. W Chrome dostępne jest jako eksperymentalny ficzer, ukryty za flagą. Na ten moment nie wiadomo, kiedy trafi do Chrome’a jako stabilny ficzer. Na pewno nie pomaga temu fakt, że specyfikacja wciąż się zmienia i nie wyszła jeszcze z grupy inkubującej nowe standardy.

Zatem wygląda na to, że w najbliższej przyszłości rozwiązania pokroju DOMPurify wciąż będą jedynymi rozwiązaniami pozwalającymi dezynfekować kod HTML. Jednak przeglądarki mają w rękawie jeszcze jednego asa… Ale to już opowieść na inną okazję!

Czemu nie rozszerzenie przeglądarki?

Pierwszą myślą zapewne są rozszerzenia przeglądarki. Dzięki nim można dodawać do przeglądarki przeróżne nowe funkcje, poczynając od blokowania reklam, a kończąc na ulepszaniu interfejsu GitHuba. Nie byłoby więc żadnym problemem dla rozszerzenia, żeby wygenerować spis treści na stronie.

Haczyk polega na tym, że napisanie rozszerzenia nie jest aż takie proste. Mimo że na przestrzeni lat zaszły zmiany, które to mocno ułatwiły, to wciąż jest to nieopłacalna ilość pracy, jeśli chcemy zrobić coś naprawdę małego. Rozszerzenia tworzy się przy pomocy specjalnego API. Oczywiście, istnieją osobne jego wersje dla przeglądarek opartych o Chromium, Firefoksa oraz Safari. W praktyce rozszerzenie napisane dla Chrome’a da się łatwo dostosować pod Firefoksa. Safari to osobna historia i wymaga odpowiednich narzędzi. Wciąż jednak można uznać proces tworzenia rozszerzenia pod wszystkie najważniejsze przeglądarki za względnie prosty. A doszliśmy do tego dzięki różnym inicjatywom standaryzującym.

Każde rozszerzenie składa się z kilku części: manifestu (metadanych), skryptów działających w tle, skryptów działających na aktualnie odwiedzanej stronie oraz UI samego rozszerzenia (np. okienka z opcjami). Jednak samo stworzenie rozszerzenia to dopiero połowa zabawy. Żeby było dostępne dla innych, trzeba je opublikować w sklepie z roszerzeniami danej przeglądarki. A każdy z nich ma inne wymagania i inny proces. Innymi słowy: dla małych rzeczy jest to gra niewarta świeczki.

Skryptozakładki

Na szczęście istnieje pewien prosty sposób, dzięki któremu da się imitować działanie rozszerzeń: bookmarklets (skryptozakładki). To nic innego, jak zakładki w przeglądarce, które, zamiast odsyłać do strony WWW, wykonują jakąś akcję. Związane jest to ze specjalnym schematem URL-i: javascript. Jak sama jego nazwa sugeruje, pozwala on na stworzenie URL-a, który wykona kod JS. Przykładowy URL może wyglądać tak:

javascript:alert(1)

Jeśli ten kod wkleimy lub wpiszemy do paska adresu w przeglądarce i naciśniemy Enter, naszym oczom okaże się wyskakujący komunikat o treści 1. Ten sam efekt można uzyskać, tworząc specjalny link. Taki link można następnie przeciągnąć na pasek zakładek przeglądarki i zapisać sobie skryptozakładkę “na później”.

Do skryptozakładek można włożyć praktycznie dowolny kod JS. Dzięki temu można zrobić np. narzędzie do sprawdzania dostępności. Trzeba jedynie pamiętać, żeby taki kod był zgodny ze skłądnią URL-i, np. białe znaki powinny być odpowiednio zakodowane. W przeglądarce służą do tego funkcja encodeURIComponent() oraz funkcja encodeURI():

console.log( 'javascript:' + encodeURIComponent( `alert( 'Hello, world!' );` ) ); // 1
console.log( encodeURI( `javascript:alert( 'Hello, world!' );` ) ); // 2

W przypadku encodeURIComponent() kodowaniu poddajemy tylko część URL-a po schemacie (1). Natomiast w przypadku encodeURI() – cały URL (2). Warto też zauważyć, że encodeURIComponent() koduje więcej znaków.

Skryptozakładki mają jednak jeden, bardzo spory haczyk: są traktowane jak zwyczajne skrypty JS. Zatem podlegają zasadom Content Security Policy. Jeśli dana strona nie zezwala na skrypty spoza konkretnego originu, skryptozakładka nie zadziała. Przeglądarki nakładają też limity na długość URL-i i dłuższe skrypty po prostu się nie zmieszczą w skryptozakładkach. Sensownym limitem wydaje się długość ok. 8000 znaków.

Skryptozakładka generująca spis treści

Kod

Napiszmy zatem kod naszej skryptozakładki generującej spis treści. Będzie ona robić kilka rzeczy:

1. wyszukiwać wszystkie nagłówki,
2. tworzyć na ich podstawie listę z linkami,
3. wstawiać tę listę jako przypięty element z lewej strony.

Z racji tego, że to skryptozakładka, całość otoczona będzie w IIFE. Dzięki temu odpali się w momencie kliknięcia w link:

( function() {

}() );

Dodajmy teraz logikę odpowiedzialną za wyszukiwanie nagłówków i tworzenie z nich listy z linkami:

( function() {
	const headings = document.querySelectorAll( 'main :where(h1, h2, h3, h4, h5, h6)' ); // 1
	let currentLevel = 1; // 2
	const nav = createList( currentLevel ); // 3
	let currentList = nav; // 4

	for ( const heading of headings ) { // 5
		setLevel( getHeadingLevel( heading ) ); // 6

		const listItem = createListItem( heading ); // 7

		currentList.append( listItem ); // 8
	}

	document.body.append( createNavContainer( nav ) ); // 9
}() );

Na początku wyszukujemy wszystkie nagłówki, które są wewnątrz elementu main (1). Dzięki temu odsiejemy nieinteresujące nas nagłówki, jak np. te od modala z ciasteczkami. Warto zauważyć jak pseudoklasa :where() pomaga nam uzyskać prostszy selektor. Potem ustawiamy aktualny poziom zagłębienia nagłówków (2), tworzymy listę nagłówków danego poziomu (3) oraz ustawiamy ją jako aktualną listę (4). Następnie iterujemy po nagłówkach (5) i dla każdego ustawiamy poziom zagłębienia (6). Następnie tworzymy nowy element listy na podstawie nagłówka (7) i dodajemy go do aktualnej listy (8). Na samym końcu tworzymy kontener z nawigacją i wstawiamy go na stronę (9).

Na pierwszy rzut oka ta logika może wydawać się dziwna, ale chcemy uzyskać listę, w której poszczególne nagłówki będą miały odpowiedni poziom zagłębienia:

• Główny nagłówek artykułu
  • Podsekcja
    • Podpodsekcja
  • Kolejna podsekcja

Żeby to uzyskać, nasz skrypt:

1. Trzyma informację o tym, na jakim poziomie zagłębienia jest.
2. Jeśli kolejny dodawany nagłówek jest na wyższym poziomie zagłębienia:
   1. Dodaje nową zagnieżdżoną listę.
   2. Dodaje do tej nowej listy link do nagłówka.
3. Jeśli kolejny dodawany nagłówek jest na niższym poziomie zagłębienia:
   1. Wyszukuje najbliższą listę, która ma ten poziom zagłębienia.
   2. Dodaje do tej listy link do nagłówka.
4. Jeśli kolejny dodawany nagłówek jest na tym samym poziomie zagłębienia:
   1. Dodaje do obecnej listy link do nagłówka.

Ten algorytm jest implementowany przez funkcję setLevel():

function setLevel( level ) {
	const lastLevel = currentLevel; // 1

	currentLevel = level; // 2

	if ( lastLevel < level ) { // 3
		const newList = createList( level ); // 4

		currentList.lastElementChild.append( newList ); // 5

		currentList = newList; // 6
	} else { // 7
		currentList = currentList.closest( `[data-level="${ level }"]` ); // 8
	}
}

Na początku zapisujemy obecny poziom zagłębienia do zmiennej lastLevel (1). Dzięki temu możemy nadpisać aktualny poziom tym przekazanym do funkcji (2). Następnie sprawdzamy, czy nowy poziom jest większy od poprzedniego (3). Jeśli tak, tworzymy nową listę z nowym poziomem zagłębienia (4) i dodajemy ją do tej obecnej (5). Następnie ustawiamy obecną listę na tę nowo utworzoną (6). Jeśli nie (7), znajdujemy najbliższą listę z nowym poziomem zagłębienia (8). Metoda #closest() tak naprawdę pokrywa punkty 3. i 4. algorytmu, ponieważ w przypadku, gdy nowy poziom zagłębienia jest taki sam jak stary, #closest() też zwróci poprawną listę.

Samym tworzeniem listy zajmuje się funkcja createList():

function createList( level ) { // 1
	const list = document.createElement( 'ul' ); // 3

	list.style.listStyleType = 'none'; // 4
	list.dataset.level = level; // 2

	return list; // 5
}

Przekazujemy jej poziom zagłębienia listy (1), który dodajemy jako atrybut [data-level] do samej listy (2). Oprócz tego, funkcja tworzy listę (3), usuwa z niej styl punktora (4), a na końcu zwraca stworzoną listę (5).

Z kolei element listy z linkiem do nagłówka jest tworzony przy pomocy funkcji createListItem():

function createListItem( heading ) {
	const listItem = document.createElement( 'li' );

	listItem.innerHTML = heading.innerHTML;

	return listItem;
}

Zawartość elementu listy (1) to po prostu prosta kopia zawartości nagłówka. Z racji tego, że nagłówki na blogu już są podlinkowane, taki zabieg w pełni wystarcza do stworzenia działającego spisu treści.

Dla kompletności dorzucam jeszcze kod funkcji getHeadingLevel() oraz createNavContainer():

function getHeadingLevel( heading ) {
	return Number( heading.tagName.replace( 'H', '' ) ); // 1
}

function createNavContainer( nav ) {
	const container = document.createElement( 'div' ); // 1

	container.style.position = 'fixed'; // 2
	container.style.insetInlineStart = 0; // 3
	container.style.insetBlockStart = 0; // 4
	container.style.border = '2px var(--secondary) solid';

	container.append( nav );

	return container;
}

Funkcja getHeadingLevel() wyciąga poziom nagłówka z nazwy jego elementu HTML (1). Wycina z niej literę H, a resztę konwertuje z ciągu tekstowego na liczbę. Z kolei funkcja createNavContainer() tworzy element div (1), a następnie nadaje mu odpowiednie style, by był przyczepiony (2) w lewym (3), górnym (4) rogu strony.

Całość kodu prezentuje się następująco:

( function() {
	const headings = document.querySelectorAll( 'main :where(h1, h2, h3, h4, h5, h6)' );
	let currentLevel = 1;
	const nav = createList( currentLevel );
	let currentList = nav;

	for ( const heading of headings ) {
		setLevel( getHeadingLevel( heading ) );

		const listItem = createListItem( heading );

		currentList.append( listItem );
	}

	document.body.append( createNavContainer( nav ) );

	function createList( level ) {
		const list = document.createElement( 'ul' );

		list.style.listStyleType = 'none';
		list.dataset.level = level;

		return list;
	}

	function setLevel( level ) {
		const lastLevel = currentLevel;

		currentLevel = level;

		if ( lastLevel < level ) {
			const newList = createList( level );

			currentList.lastElementChild.append( newList );

			currentList = newList;
		} else {
			currentList = currentList.closest( `[data-level="${ level }"]` );
		}
	}

	function getHeadingLevel( heading ) {
		return Number( heading.tagName.replace( 'H', '' ) );
	}

	function createListItem( heading ) {
		const listItem = document.createElement( 'li' );

		listItem.innerHTML = heading.innerHTML;

		return listItem;
	}

	function createNavContainer( nav ) {
		const container = document.createElement( 'div' );

		container.style.position = 'fixed';
		container.style.insetInlineStart = 0;
		container.style.insetBlockStart = 0;
		container.style.border = '2px var(--secondary) solid';

		container.append( nav );

		return container;
	}
}() );

Tworzenie skryptozakładki

Tak naprawdę samo stworzenie skryptozakładki sprowadza się do przepuszczenia powyższego kodu JS przez funkcję encodeURIComponent(), a następnie zrobienie z tego URL-a. Ale że to nudne, przygotowałem proste narzędzie do konwersji:

Generator składa się z dwóch zasadniczych części: formularza w HTML-u oraz JS-owego kodu jego obsługi. Sam formularz jest prosty:

<form id="generator">
	<p><label for="code">JS code</label></p>
	<p><textarea name="code" id="code"></textarea></p> <!-- 1 -->
	<p><button>Generate</button></p>
	<p><output id="bookmarklet"></output></p> <!-- 2 -->
	<p><a href="" id="link" hidden>Drag me to your bookmark bar</a></p> <!-- 3 -->
</form>

Istotne są w nim tak naprawdę trzy elementy:

1. pole tekstowe, w którym trzeba wprowadzić kod do przetworzenia,
2. element output, w którym będzie wyświetlany gotowy URL,
3. link, dzięki któremu będzie można łatwo zainstalować skryptozakładkę w przeglądarce.

Natomiast kod obsługujący ten formularz prezentuje się następująco:

const form = document.querySelector( '#generator' );
const output = document.querySelector( '#bookmarklet' );
const link = document.querySelector( '#link' );

form.addEventListener( 'submit', ( evt ) => { // 1
	evt.preventDefault(); // 2

	const formData = new FormData( evt.target ); // 3
	const rawCode = formData.get( 'code' ); // 4

	if ( rawCode.trim() === '' ) { // 5
		link.hidden = true; // 6
		output.value = ''; // 7

		return; // 8
	}

	const optimizedCode = rawCode.replaceAll( /[\t\n]/gu, '' ); // 9
	const bookmarklet = `javascript:${ encodeURIComponent( optimizedCode ) }`; // 10

	output.value = bookmarklet; // 11
	link.href = bookmarklet; // 12
	link.hidden = false; // 13
} );

Nasłuchujemy na zdarzenie submit formularza (1). Blokujemy domyślną akcję (2), a następnie wyciągamy dane z formularza (3). Sprawdzamy, czy zawartość pola tekstowego (4) jest pusta (5). Jeśli tak, ukrywamy linka (6), resetujemy zawartość elementu output (7) i wychodzimy z funkcji (8). W przeciwnym wypadku, optymalizujemy zawartość pola tekstowego poprzez usunięcie tabulatorów i znaków nowej linii (9). Dzięki temu pozbywamy się sporej części białych znaków i tym samym – zmniejszamy rozmiar wynikowego URL-a. Na sam koniec tworzymy URL-a (10) i wsadzamy go do elementu output (11) oraz do linku (12), który przy okazji pokazujemy (13).

Gotowa skryptozakładka

Jeśli do powyższego generatora wkleimy nasz kod generujący spis treści, otrzymamy następującego URL-a:

javascript:(%20function()%20%7Bconst%20headings%20%3D%20document.querySelectorAll(%20'main%20%3Awhere(h1%2C%20h2%2C%20h3%2C%20h4%2C%20h5%2C%20h6)'%20)%3Blet%20currentLevel%20%3D%201%3Bconst%20nav%20%3D%20createList(%20currentLevel%20)%3Blet%20currentList%20%3D%20nav%3Bfor%20(%20const%20heading%20of%20headings%20)%20%7BsetLevel(%20getHeadingLevel(%20heading%20)%20)%3Bconst%20listItem%20%3D%20createListItem(%20heading%20)%3BcurrentList.append(%20listItem%20)%3B%7Ddocument.body.append(%20createNavContainer(%20nav%20)%20)%3Bfunction%20createList(%20level%20)%20%7Bconst%20list%20%3D%20document.createElement(%20'ul'%20)%3Blist.style.listStyleType%20%3D%20'none'%3Blist.dataset.level%20%3D%20level%3Breturn%20list%3B%7Dfunction%20setLevel(%20level%20)%20%7Bconst%20lastLevel%20%3D%20currentLevel%3BcurrentLevel%20%3D%20level%3Bif%20(%20lastLevel%20%3C%20level%20)%20%7Bconst%20newList%20%3D%20createList(%20level%20)%3BcurrentList.lastElementChild.append(%20newList%20)%3BcurrentList%20%3D%20newList%3B%7D%20else%20%7BcurrentList%20%3D%20currentList.closest(%20%60%5Bdata-level%3D%22%24%7B%20level%20%7D%22%5D%60%20)%3B%7D%7Dfunction%20getHeadingLevel(%20heading%20)%20%7Breturn%20Number(%20heading.tagName.replace(%20'H'%2C%20''%20)%20)%3B%7Dfunction%20createListItem(%20heading%20)%20%7Bconst%20listItem%20%3D%20document.createElement(%20'li'%20)%3BlistItem.innerHTML%20%3D%20heading.innerHTML%3Breturn%20listItem%3B%7Dfunction%20createNavContainer(%20nav%20)%20%7Bconst%20container%20%3D%20document.createElement(%20'div'%20)%3Bcontainer.style.position%20%3D%20'fixed'%3Bcontainer.style.insetInlineStart%20%3D%200%3Bcontainer.style.insetBlockStart%20%3D%200%3Bcontainer.style.border%20%3D%20'2px%20var(--secondary)%20solid'%3Bcontainer.append(%20nav%20)%3Breturn%20container%3B%7D%7D()%20)%3B

Teraz wystarczy go zapisać jako zakładkę (np. przeciągając ten pomocny link). Kiedy już ją odpalimy na wybranym artykule, po lewej stronie powinien się pojawić spis treści:

Tak oto w zamierzchłych czasach rozszerzało się możliwości przeglądarki!

Poważne kłótnie

Gdy pisałem artykuł o dygresjach, próbowałem pokazać, jak wygląda składnia nowego rozwiązania. Użyłem wówczas zapisu ze znakami ucieczki:

{\% note %}Treść dygresji{\% endnote %}

Wszystko po to, żeby Eleventy nie potraktował tego jako kodu w składni Liquida i nie wygenerował dygresji.

Myślałem, że w ten prymitywny sposób udało mi się ominąć problem. A potem pojawił się wpis o tworzeniu dyskusji przy pomocy GitHub Actions i okazało się, że tak nie do końca:

Ten fragment kodu miał wyglądać następująco:

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # 17

GitHub Actions do wstawiania wartości zmiennych używa takiej samej składni co Liquid, czyli wąsów ({{ }}). Zatem Eleventy spróbowało podstawić wartość zmiennej z Liquida o nazwie secrets.GITHUB_TOKEN do treści. Takiej zmiennej jednak nie ma, więc ostatecznie zostało puste miejsce.

Stwierdziłem zatem, że coś trzeba z tym zrobić. W końcu musi być jakiś sposób, żeby ominąć problem nakładających się składni!

Rozwiązanie

Zajrzałem więc do dokumentacji Liquida. Okazało się, że, faktycznie, jest coś, co pozwoli mi rozwiązać mój problem: tag raw. Jeśli otoczy się nim fragment treści, to nie będzie on parsowany przez Liquida. Tym samym – powinien przetrwać w niezmienionej formie i wylądować w wynikowym pliku HTML!

Co jeszcze ciekawsze, okazało się, że… już kiedyś ten tag zastosowałem. A dokładniej: we wpisie o formatowaniu tekstu przy pomocy metody Array#reduce(). Jakoś totalnie o tym zapomniałem. Niemniej, ponownie uzbrojony w tę wiedzę mogłem teraz poprawić problematyczne wpisy!

Tylko że… jestem leniwym i zapominalskim człowiekiem. Raz, że nie chce mi się wszędzie pisać tego tagu raw; dwa – nie jest mi on potrzebny na tyle często, żebym o nim pamiętał. Przy kolejnym tego typu problemie jeszcze raz bym musiał przechodzić cały proces przypominania sobie o tym rozwiązaniu. Wypadałoby to jakoś zautomatyzować!

Dobre rozwiązanie

Na szczęście Eleventy udostępnia preprocesory. Pozwalają one zmodyfikować pliki wpisów, zanim trafią one do parserów Liquida i Markdowna. Jest więc to idealny moment, żeby zaaplikować tag raw w odpowiednich miejscach!

Tak wygląda mój preprocesor:

const codeBlockRegex = /^```(?:.+)?\n(?:.|\n)+?\n```\n/gmu; // 4

export function createLiquidPreprocessor( eleventyConfig ) { // 1
	eleventyConfig.addPreprocessor( 'liquidPreprocessor', 'md', ( _, content ) => { // 2
		return content.replaceAll( codeBlockRegex, '{\% raw %}$&{\% endraw %}' ); // 3
	} );
}

Tworzymy funkcję createLiquidPreprocessor() (1), którą eksportujemy. Ta funkcja jako argument przyjmuje obiekt konfiguracyjny Eleventy. Wywołujemy jego metodę #addPreprocessor() (2) i przekazujemy mu nasz preprocesor. Podajemy jego nazwę (liquidPreprocessor) oraz rozszerzenie pliku, dla którego ma się odpalać (md). Sam preprocesor przekazujemy jako callback. Jego drugi argument to treść pliku z wpisem. Z callbacku zwracamy treść z podmienionymi wszystkimi blokami kodu na takie otoczone tagiem raw (3). Bloki kodu wykrywamy przy pomocy wyrażenia regularnego (4):

1. ^``` oznacza linię, która zaczyna się od potrójnego grawisa (`),
2. (?:.+)? oznacza nazwę języka, która może składać się z dowolnej liczby dowolnych znaków (.+) oraz może wystąpić raz lub wcale (?),
3. \n oznacza nową linię, następującą po grawisach i opcjonalnej nazwie języka,
4. (?:.|\n)+? oznacza zawartość bloczka kodu, która może składać się z dowolnych znaków oraz nowych linii,
5. \n```\n oznacza zakończenie bloczka, czyli potrójny grawis otoczony znakami nowej linii (inaczej mówiąc: linia, w której znajdują się wyłącznie trzy grawisy).

Natomiast samą podmianę robimy przy pomocy wzorca '{% raw %}$&{\% endraw %}'. Metoda #replaceAll() pozwala używać specjalnych wyrażeń, które dają dostęp do rzeczy znalezionych przez wyrażenie regularne. W naszym wypadku używamy wyrażenia $& oznaczającego cały znaleziony ciąg.

Ostatnim etapem jest zaimportowanie funkcji createLiquidPreprocessor() w pliku eleventyConfig.js i wywołanie jej. Od teraz wszystkie bloczki kodu w plikach .md będą automatycznie otaczane przy pomocy tagów raw!

To rozwiązanie ma jedną wadę: nie pozwala używać podstawiania zmiennych Liquidowych wewnątrz bloczków kodu:

const zmienna = '{{ zmiennaZLiquida }}';

Zamiast wartości zmiennej, powyższy kod wyświetli po prostu {{ zmiennaZLiquida }}. Niemniej od momentu powstania bloga ani razu tego nie potrzebowałem, więc… brzmi jak coś, co mogę odłożyć na później.

Tak oto niniejszy blog ulepszył się o kolejną, małą rzecz!

Co udało się dotąd osiągnąć?

Dla przypomnienia: problem z komentarzami polegał na tym, że nie istniały dyskusje dla wszystkich wpisów. Przez to osoby, które nie zaakceptowały ciasteczek, nie miały możliwości dodawania komentarzy.

Dlatego stworzyłem skrypt, który sprawdza, jakie dyskusje istnieją, a następnie tworzy wszystkie brakujące. W tym celu wykorzystałem APi GitHuba i personalny token dostępowy. Niemniej to rozwiązanie naprawia komentarze tylko już w istniejących wpisach. Jeśli teraz dodałbym nowy, w nim problem znowu by się pojawił. Więc musiałbym regularnie odpalać swój naprawiający dyskusje skrypt… Albo przygotować rozwiązanie, które dodaje dyskusje dla każdego nowego wpisu.

Na ratunek GitHub Actions!

Z racji tego, że moim hobby jest spędzanie kilku godzin na próbie automatyzacji 3-minutowych czynności, postanowiłem zautomatyzować dodawanie dyskusji dla każdego nowego wpisu. Na całe szczęście GitHub udostępnia narzędzie, które to zdecydowanie ułatwia – GitHub Actions. Jest to rozwiązanie typu CI/CD – Continuous Integration (Ciągła Integracja)/Continuous Delivery (Ciągłe Dostarczanie). Tego typu rozwiązania służą do monitoringu zmian w kodzie. Jeśli coś trafia do repozytorium, system CI/CD dba o to, by spełniało określone standardy. Odpali testy, wygeneruje dokumentację, a następnie może nawet automatycznie opublikować paczkę w npm-ie czy innym repozytorium pakietów. Słowem: automatyzuje te części procesu wypuszczania oprogramowania, które warto zautomatyzować.

GitHub Actions integrują się ze zdarzeniami, które mogą zajść w repozytorium na GitHubie, takimi jak dodanie nowego issue czy wypchnięcie zmian do konkretnego brancha. Dzięki temu można np. sprawdzić, czy osoba zgłaszająca błąd dodała potrzebne informacje, albo wypuścić nową wersję pakietu npm za każdym razem, gdy nowy kod trafi do głównego brancha. Można też… dodać nową dyskusję, gdy pojawi się nowy wpis!

Konfiguracja akcji

Żeby móc odpalić akcję, trzeba dodać do repozytorium odpowiedni plik konfiguracyjny, tzw. workflow. Jest to plik w formacie YAML, który zawiera informacje, jakie akcje chcemy odpalić oraz kiedy. Ten plik następnie umieszcza się w katalogu .github/workflows.

Dodajmy zatem plik .github/workflows/fix-discussions.yml:

name: Fix discussions # 1

permissions: # 2
  discussions: write # 3

on: # 4
  push:
    branches:
      - main #5
    paths:
      - 'src/_posts/**/*.md' #6

jobs: # 7
  fix-discussions: # 8
    runs-on: ubuntu-latest # 9
    steps: # 10
      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # 11
        with:
          fetch-depth: 2 # 12
      - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # 13
        with:
          node-version: 24 # 14
      - run: npm install --no-save @octokit/action # 15
      - run: node .github/actions/fix-discussions.mjs # 16
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # 17
          CATEGORY_ID: '[ciach]' # 18
          POSTS_DIR_PATH: 'src/_posts' # 19
          BLOG_URL: 'https://blog.comandeer.pl' # 20

Na początku podajemy nazwę workflowu (1). Następnie określamy uprawnienia dla domyślnego tokena dostępowego (2). Każdy workflow posiada token, który jest wykorzystywany do autoryzacji wszystkich operacji. W naszym wypadku token musi umożliwiać dodawanie dyskusji (3), więc dostaje tylko takie uprawnienia. Następnie określamy, kiedy workflow ma się wykonać (4). Chcemy, żeby zachodził, gdy zmiany zostaną wypchnięte do brancha main (5) i do tego dotyczyć będą plików wpisów (6). Potem ustalamy, co tak naprawdę ma się stać, tworząc zadania – jobs (7). W naszym wypadku jest tylko jedno zadanie, fix-discussions (8). Odpalamy je na Linuksie (9). Następnie w steps (10) ustalamy poszczególne kroki zadania. Na początku korzystamy z akcji actions/checkout (11). Pobiera ona zawartość naszego repozytorium, pozwalając na nim pracować. W naszym przypadku dodatkowo musimy ustawić opcję fetch_depth na 2 (12). Domyślnie akcja pobiera tylko ostatni commit, a my potrzebujemy dwóch ostatnich (przy logice akcji ten wymóg się wyjaśni). Kolejnym krokiem jest wykorzystanie akcji actions/setup-node w celu instalacji Node.js (13). Zaznaczamy, że chcemy wersję 24 (14). Gdy już Node.js zostanie zainstalowany, instalujemy pakiet npm @octokit/action (15). To specjalna odmiana wykorzystywanej przez nas ostatnio biblioteki Octokit.js, dostosowana pod GitHub Actions. Na sam koniec uruchamiamy nasz skrypt JS (16), przekazując mu szereg zmiennych środowiskowych: token dostępowy GitHuba (17), ID kategorii dyskusji (18), względną ścieżkę do katalogu z wpisami (19) oraz URL bloga (20).

Logika akcji

Skrypt, będący “mózgiem” naszego workflowu, znajduje się w pliku .github/actions/fix-discussions.mjs. Jego główna logika prezentuje się następująco:

const octokit = new Octokit();

await main();

async function main() { // 1
	const fullPostsDirPath = resolvePath( cwd(), env.POSTS_DIR_PATH );
	const postFiles = getPostFiles( env.GITHUB_SHA, env.POSTS_DIR_PATH ); // 4
	const posts = await getPostMetadata( postFiles ); // 2
	const missingPosts = await getPostsWithoutDiscussions( { // 5
		posts,
		repository: env.GITHUB_REPOSITORY
	} );

	console.log( 'Brakujących dyskusji:', missingPosts.length );

	await createMissingDiscussions( { // 3
		repository: env.GITHUB_REPOSITORY,
		categoryId: env.CATEGORY_ID,
		posts: missingPosts,
		blogUrl: env.BLOG_URL
	} );
}

Całość zamknięta jest w asynchronicznej funkcji main() (1). W gruncie rzeczy jest ona bardzo podobna do wczorajszego kodu. Wewnątrz funkcji getPostMetadata() (2) została zamknięta pętla wyciągająca metadane dla każdego wpisu. Sam kod je wyciągający jest identyczny. Tak samo praktycznie bez zmian została funkcja tworząca nowe dyskusje, createMissingDiscussions() (3). Jedyną różnicą jest przekazywanie jej zmiennej środowiskowej GITHUB_REPOSITORY, zamiast osobno właściciela i nazwy repozytorium. Ta zmienna środowiskowa ma format <WŁAŚCICIEL>/<REPOZYTORIUM>, więc uzyskanie właściciela i nazwy sprowadza się do podzielenia wartości zmiennej na znaku /. Zmiany natomiast zaszły w funkcji pobierającej listę plików z wpisami (4) oraz w funkcji sprawdzającej, czy dla podanych postów istnieją dyskusje (5).

Przyjrzyjmy się najpierw funkcji getPostFiles():

import { execSync } from 'node:child_process'; // 2

[…]

function getPostFiles( commitHash, postsDirPath ) { // 1
	const rawCommitInfo = execSync( `git diff-tree --no-commit-id --name-only ${ commitHash } -r` ); // 3
	const commitInfo = rawCommitInfo.toString( 'utf-8' ); // 4
	const lines = commitInfo.split( '\n' ); // 5

	return lines // 8
		.filter( ( line ) => {
			const trimmedLine = line.trim();

			return trimmedLine.startsWith( postsDirPath ) && trimmedLine.endsWith( '.md' ); // 6
		} )
		.map( ( path ) => {
			return resolvePath( cwd(), path.trim() ); // 7
		} );
}

Funkcja przyjmuje dwa argumenty (1): hash aktualnego commita oraz względną ścieżkę do katalogu z wpisami. Na sam początek wykorzystujemy funkcję execSync() z wbudowanego modułu node:child_process (2), aby wywołać komendę git diff-tree na przekazanym hashu commita (3). Komenda ta zwróci nam listę plików zmienionych w danym commicie. A że lista ta jest generowana na podstawie porównania tego commita z poprzednimi, stąd potrzeba wymuszenia na akcji actions/checkout pobrania dwóch ostatnich commitów (domyślnie pobiera tylko ostatni). Funkcja execSync() zwróci nam wynik w postaci bufora, więc musimy go skonwertować na ciąg znaków (4). Z racji tego, że git diff-tree wyświetla jedną nazwę pliku w linii, musimy podzielić wynik tej komendy na poszczególne linie (5). Następnie filtrujemy tablicę linii i znajdujemy tylko te, które dotyczą plików z wpisami (6). Następnie dla każdego wpisu rozwiązujemy pełną ścieżkę (7). Tak spreparowaną tablicę ścieżek zwracamy z funkcji (8).

Przejdźmy teraz do funkcji getPostsWithoutDiscussions():

async function getPostsWithoutDiscussions( options ) {
	const postsWithoutDiscussions = []; // 1

	for ( const post of options.posts ) { // 2
		if ( await isMissingDiscussion( options.repository, post.slug ) ) { // 3
			postsWithoutDiscussions.push( post ); // 4
		}

		await sleep( getRandomNumber( 1, 5 ) ); // 5
	}

	return postsWithoutDiscussions; // 6
}

Na początku tworzymy w niej tablicę wpisów, które nie mają dyskusji (1). Następnie iterujemy po wszystkich przekazanych postach (2) i sprawdzamy, czy każdy z nich ma swoją dyskusję (3). Jeśli nie, trafia do tablicy (4). Następnie odczekujemy losową liczbę sekund (5), żeby nie nadziać się na limity GitHub API. Jak już przerobimy wszystkie posty, zwracamy naszą tablicę (6).

Przyjrzyjmy się więc funkcji isMissingDiscussion():

async function isMissingDiscussion( repository, title ) {
	const searchQuery = `repo:${ repository } in:title "${ title }"`; // 2
	/* 1 */ const graphqlQuery = `
		query($searchQuery: String!) {
			search(query: $searchQuery, type: DISCUSSION, first: 1) {
				edges {
					node {
						... on Discussion {
							title
						}
					}
				}
			}
		}
	`;

	const result = await octokit.graphql( graphqlQuery, {
		searchQuery
	} );
	const discussions = result.search.edges.map( ( edge ) => {
		return edge.node;
	} );

	return discussions.findIndex( ( discussion ) =>  {
		return discussion.title === title; // 3
	} ) === -1; // 4
}

Zawiera ona zapytanie GraphQL (1), które korzysta z wyszukiwarki GitHuba, żeby znaleźć dyskusję o konkretnym tytule. Samo zapytanie do wyszukiwarki (2) można… testować w wyszukiwarce GitHuba – składnia jest identyczna. Po otrzymaniu wyniku zapytania z API, sprawdzamy, czy znajduje się w nim rekord dla naszego wpisu (3). Jeśli tak, funkcja zwróci false. W innym wypadku zwróci true. Dzieje się tak, ponieważ metoda Array#findIndex() zwróci -1 (4) tylko wtedy, gdy szukanej rzeczy nie ma w tablicy.

I to w sumie tyle, reszta logiki skryptu działa praktycznie identycznie jak tego wczorajszego. Ale dzięki przeniesieniu tej logiki do akcji, dyskusje dla nowych wpisów powinny dodawać się automatycznie. Jak choćby dla tego wpisu!

A jeśli powyższy link jednak nie działa, to jutro zapewne kolejna część tej sagi…

Jak działają komentarze?

Na swojej stronie używam systemu Giscus. Pozwala on dodawać komentarze w formie dyskusji na GitHubie. Każdy wpis ma swoją własną dyskusję. Tak dodane komentarze są wyświetlone na dole, pod każdym wpisem:

Działa to całkiem przyzwoicie. Minusem jest wymóg, aby każda komentująca osoba miała konto na GitHubie. Wydaje mi się jednak, że z uwagi na grupę docelową bloga jest to akceptowalny kompromis. Jest też drugi minus: Giscus wymaga zarówno JS-a, jak i zaakceptowania ciasteczek. Co się stanie, jeśli zabraknie choć jednego z nich? Zamiast komentarzy, pojawi się link do dyskusji na GitHubie:

I właśnie tutaj pojawia się zgłoszony błąd! W przypadku, gdy dany post ma już jakieś komentarze, link zaprowadzi nas do istniejącej dyskusji. Jednak, gdy post dotąd nie został skomentowany, dana dyskusja nie istnieje, a komentująca osoba nie jest w stanie jej sama stworzyć. Giscus robi to automatycznie przy pierwszym komentarzu. A że nie chcę odcinać nawet części czytających od możliwości komentowania, stwierdziłem, że zainteresuję się problemem i postaram znaleźć jakieś rozwiązanie.

(Częściowe) rozwiązanie

Logicznie nasuwającym się rozwiązaniem jest stworzenie brakujących dyskusji – tak, aby dla każdego wpisu istniała jedna. Tym zajmiemy się dzisiaj! Napiszemy skrypt w Node.js, który:

1. stworzy listę wszystkich wpisów,
2. sprawdzi, czy istnieją dla nich dyskusje,
3. stworzy wszystkie brakujące dyskusje.

To rozwiązanie jednak naprawia tylko część problemu. Dyskusje powstaną bowiem dla już istniejących wpisów. Musiałbym regularnie odpalać ten skrypt, żeby wykrywać nowe wpisy i dodawać do nich dyskusje. Wygodniejszym rozwiązaniem byłoby automatyczne tworzenie dyskusji w momencie, gdy nowy wpis zostaje wypchany do repozytorium. Tym zajmiemy się kiedy indziej. Na razie skupimy się na naprawieniu dyskusji dla już istniejących wpisów.

Stworzenie listy wpisów

Struktura plików bloga jest w miarę uporządkowana. Wszystkie wpisy znajdują się w katalogu src/_posts, w podkatalogu odpowiedniej kategorii. Same wpisy to pliki .md. Zatem wyciągnięcie listy wpisów w dużej mierze sprowadza się do wyszukania wszystkich plików .md w katalogu src/_posts. Dokładnie do takich zadań został stworzony glob! W Node.js od wersji 22 istnieje odpowiednia funkcja od tego. Wystarczy ją wykorzystać do wyciągnięcia listy plików .md:

import { glob } from 'node:fs/promises'; // 1

const postsDirPath = '[ciach]blog/src/_posts'; // 4
const postFiles = glob( '**/*.md', { // 2
	cwd: postsDirPath // 3
} );

for await ( const postFile of  postFiles ) { // 5
	console.log( postFile ); // 6
}

Na początku importujemy funkcję glob() z wbudowanego modułu node:fs (1). Następnie wywołujemy ją ze wzorcem **/*.md (2) oraz katalogiem (3) ustawionym na absolutną ścieżkę do katalogu z wpisami bloga (4). Następnie w pętli (5) wyświetlamy wszystkie pliki (6). Powinniśmy uzyskać mniej więcej taką listę:

standardy-sieciowe/2017-03-19-drzewko-dostepnosci-udostepnione.md
standardy-sieciowe/2017-04-02-web-components-koszmar-minionego-lata.md
standardy-sieciowe/2017-04-09-potrzebujemy-zachowan-nie-dziedziczenia.md
standardy-sieciowe/2018-01-05-pyrrusowe-zwyciestwo.md
standardy-sieciowe/2018-01-23-zawieszenie-broni.md
[…]

Jak widać, uzyskaliśmy ścieżki do plików względem katalogu z wpisami. Wróćmy jeszcze na chwilę do samego wzorca:

**/*.md

Nie będę wchodził tutaj w szczegóły składni globa, ale ten wzorzec oznacza “wszystkie pliki z rozszerzeniem .md, w dowolnym podkatalogu obecnego katalogu”. Gdybyśmy ograniczyli się tylko do *.md, glob nic by nie znalazł (nie wszedłby do żadnego z podkatalogów kategorii).

No dobrze, ale surowa lista plików to jedynie połowa sukcesu. Zobaczmy, jak wygląda przykładowa dyskusja stworzona przez Giscusa:

Tak naprawdę potrzebujemy pomrowa…! Czyli sluga, a więc – ostatnią część URL-a wpisu:

https://blog.comandeer.pl/blog-2.0

W przypadku mojego bloga slugiem jest wszystko to, co następuje po domenie, a więc – ścieżka.

Tę możemy uzyskać z tzw. front matter (strony tytułowej). To sekcja na początku pliku .md, wydzielona przy pomocy --- i zawierająca metadane wpisu w formacie YAML. W przypadku mojego bloga jedną z metadanych jest permalink, a więc – ostateczna nazwa wynikowego pliku HTML:

permalink: /blog-2.0.html

A stąd już prosta droga do ścieżki, która – dzięki konfiguracji backendu – pomija rozszerzenie .html. Wystarczy zatem… sparsować YAML-a, wyciągnąć z niego wartość danej permalink i obciąć z niej .html! A jak już to będziemy robić, to warto przy okazji zainteresować się inną metadaną, comments, która określa, czy dany wpis powinien mieć komentarze, czy nie. Jak na razie tylko jeden wpis nie ma komentarzy, ale nie wykluczam, że pojawią się kolejne w przyszłości. Możemy też od razu wyciągnąć daną description, czyli opis wpisu, który przyda nam się przy tworzeniu dyskusji.

Sparsujmy zatem YAML-a! Na całe szczęście nie musimy dokładnie parsować całej strony tytułowej, wystarczy nam wyszukanie w niej trzech danych. A do tego wykorzystać możemy wyrażenia regularne. Przystąpmy do pracy:

import { glob, readFile } from 'node:fs/promises'; // 1
import { resolve as resolvePath } from 'node:path'; // 2

[…]

const posts = []; // 3

for await ( const postFile of  postFiles ) {
	const postFilePath = resolvePath( postsDirPath, postFile ); // 4
	const postContent = await readFile( postFilePath, 'utf-8' ); // 5
	const postMetadata = getMetadata( postContent ); // 6

	if ( postMetadata.comments ) { // 7
		posts.push( postMetadata ); // 8
	}
}

Na początku importujemy dwie dodatkowe funkcje: readFile() (1) do odczytywania zawartości plików oraz resolve() (2) do rozwiązywania pełnych ścieżek do plików. Następnie tworzymy tablicę posts (3), w której będziemy przechowywać metadane wpisów zezwalających na komentarze. Z kolei w pętli rozwiązujemy pełną ścieżkę pliku wpisu względem katalogu z wpisami (4), a następnie używamy jej do odczytania zawartości pliku (5). Tę zawartość przekazujemy funkcji getMetadata() (6), której zadaniem jest wyciągnięcie metadanych ze strony tytułowej. Jeśli w metadanych jest informacja, że wpis zezwala na komentarze (7), metadane są umieszczane w tablicy posts (8).

Z kolei funkcja getMetadata() prezentuje się następująco:

[…]

const FRONT_MATTER_REGEX = /^---\n(?<content>(?:.|\n)+)\n---/u; // 2

[…]

function getMetadata( content ) {
	const frontMatter = content.match( FRONT_MATTER_REGEX ); // 1
	const lines = frontMatter.groups.content.split( '\n' ); // 3

	return lines.reduce( ( metadata, line ) => { // 4
		[…]
		return metadata;
	}, {} );
}

Na początku wyszukujemy stronę tytułową w treści wpisu (1) przy pomocy wyrażenia regularnego (2). Szuka ono ciągu, który zaczyna się od trzech myślników (-), po których następuje znak nowej linii (\n), po niej interesująca nas treść, którą zapisujemy do grupy content, a po treści następuje znowu znak nowej linii (\n) oraz ponownie trzy myślniki. Następnie treść strony tytułowej dzielimy na poszczególne linie (3). Tak uzyskaną tablicę z treścią każdej linii przekształcamy na obiekt z metadanymi (4).

Z kolei same przekształcenia zależą od tego, jaką linię akurat parsujemy. Rozpoznamy to poprzez sprawdzenie, czy jej treść zaczyna się od nazwy poszukiwanej przez nas metadanej:

if ( line.startsWith( '<nazwa metadanej>') ) {
	// zrób coś
}

Dla metadanej permalink kod wygląda następująco:

const PERMALINK_TRIM_REGEX = /\.html$/gu; // 5
[…]

if ( line.startsWith( 'permalink' ) ) { // 1
    const [ , lineContent ] = line.split( ':' ); // 2

    return {
        ...metadata, // 3
        slug: lineContent.trim().replace( PERMALINK_TRIM_REGEX, '' ) // 4
    }
}

Sprawdzamy, czy mamy do czynienia z odpowiednią daną (1). Następnie dzielimy linię na dwie części (2): niepotrzebną nam nazwę metadanej oraz jej wartość. Dzielenie jest robione na znaku dwukropka (:). Następnie zwracamy obiekt z metadanymi. Kopiujemy już istniejące (3), po czym dodajemy własność slug (4). Jej wartością jest wartość metadanej, pozbawiona białych znaków z początku i końca, oraz z usuniętym niepotrzebnym rozszerzeniem .html z końca. Usunięcia dokonaliśmy przez zastąpienie rozszerzenia, wyszukanego wyrażeniem regularnym (5), przez pusty ciąg.

Podobnie wygląda to w przypadku metadanej description:

[…]

const DESCRIPTION_TRIM_REGEX = /^"|"$/gu; // 1

[…]

if ( line.startsWith( 'description' ) ) {
    const [ , lineContent ] = line.split( ':' );

    return {
        ...metadata,
        description: lineContent.trim().replace( DESCRIPTION_TRIM_REGEX, '' )
    };
}

Jedyna różnica polega na tym, że w tym przypadku zamiast rozszerzenia .html usuwamy cudzysłowy (1), którymi otoczona jest większość opisów.

Do tego jeszcze dorzucamy obsługę metadanej comments:

if ( line.startsWith( 'comments' ) ) {
    const [ , lineContent ] = line.split( ':' );

    return {
        ...metadata,
        comments: lineContent.trim() === 'true' ? true : false // 1
    };
}

W tym przypadku zamiast zawartości metadanej, zwracamy true albo false – w zależności od tego, czy metadana miała wartość true lub false (1). Z racji tego, że parsujemy YAML-a ręcznie, cała zawartość strony tytułowej jest tekstem, więc musimy tę konwersję zrobić sami.

I w końcu mamy listę wszystkich wpisów, które mają mieć komentarze! Teraz pora przystąpić do drugiej części zadania.

Sprawdzenie, czy dla wpisów istnieją dyskusje

Sprawdzenie, jakie dyskusje istnieją w repozytorium bloga, wymaga użycia API GitHuba. Na całe szczęście, dla Node.js istnieje biblioteka Octokit.js, która zdecydowanie to ułatwia. Wypada ją zatem zainstalować:

npm install octokit

Żeby jednak móc ją użyć do połączenia się z API, trzeba stworzyć nowy token dostępowy. Najlepiej, żeby miał jak najmniejsze uprawnienia. W tym przypadku: dostęp tylko do repozytorium bloga, a w nim – tylko do dyskusji.

Mimo minimalnych uprawnień, taki token najlepiej trzymać poza kodem, np. w pliku .env. Jest to na tyle popularna technika, że Node od wersji 20.12 ma wbudowane funkcje w celu jej wspierania. Zacznijmy od stworzenia pliku .env:

GITHUB_TOKEN="[ciach]" # 1
POSTS_DIR_PATH="[ciach]/blog/src/_posts" # 2
REPO_OWNER="Comandeer" # 3
REPO_NAME="blog" # 4
CATEGORY_ID="[ciach]" # 5

Stworzyliśmy w nim sześć zmiennych:

1. GITHUB_TOKEN – token dostępowy GitHuba,
2. POST_DIR_PATH – ścieżkę do katalogu z postami,
3. REPO_OWNER – nazwę właściciela repozytorium na GitHubie,
4. REPO_NAME – nazwę repozytorium na GitHubie,
5. CATEGORY_ID – ID kategorii na GitHub Discussions (można użyć Giscusa, żeby je uzyskać),
6. BLOG_URL – adres bloga (bez / na końcu).

Dzięki temu całość konfiguracji skryptu jest poza skryptem i nie trzeba będzie dłużej zmieniać kodu, żeby np. zaktualizować ścieżkę. A i trzymanie tego w zewnętrznym pliku sprawia, że jest zdecydowanie mniejsza szansa, że przez przypadek wypchamy do repo token.

Pora wczytać zawartość pliku .env do zmiennych środowiskowych:

import { loadEnvFile, env } from 'node:process'; // 1
import { Ocktokit } from 'octokit'; // 4

loadEnvFile(); // 2

[…]

const postsDirPath = env.POSTS_DIR_PATH; // 3

Najpierw importujemy funkcję loadEnvFile() oraz zmienną env z node:process (1). Następnie wywołujemy loadEnvFile() (2), żeby stworzyć zmienne środowiskowe na podstawie pliku .env. Na końcu używamy tak wczytanej zmiennej środowiskowej do określenia położenia katalogu z wpisami (3). Przy okazji możemy też od razu zaimportować bibliotekę octokit (4).

Pora stworzyć funkcję, która pobierze dla nas wszystkie dyskusje z kategorii przeznaczonej na komentarze:

const octokit = new Octokit( { // 9
	auth: process.env.GITHUB_TOKEN // 10
} );
async function getExistingDiscussions( options ) {
	/* 1 */ const query = `
		query($owner: String!, $repo: String!, $categoryId: ID!, $cursor: String) {
			repository(owner: $owner, name: $repo) {
				discussions(
					first: 100,
					after: $cursor,
					categoryId: $categoryId
				) {
					nodes {
						title
					}
					pageInfo {
						hasNextPage
						endCursor
					}
				}
			}
		}`;
	const discussions = [];
	let hasNextPage = false; // 4
	let cursor; // 7

	do { // 2
		const result = await octokit.graphql( query, { // 8
			...options,
			cursor
		});
		const { nodes, pageInfo } = result.repository.discussions; // 11

		discussions.push( ...nodes ); // 12

		hasNextPage = pageInfo.hasNextPage; // 5
		cursor = pageInfo.endCursor; // 6
	} while ( hasNextPage ); // 3

	return discussions; // 13
}

Funkcja wygląda dość przerażająco – ale to głównie z uwagi na spore zapytanie GraphQL (1). Nie będę wchodził w szczegóły tego języka. W dużym skrócie: to zapytanie pobierze nam wszystkie dyskusje, które są w podanej kategorii dyskusji. Reszta funkcji to obsługa tego zapytania. Tworzymy pętlę do/while (2), która wykona się co najmniej raz, a kolejne wywołania zależeć będą od tego, czy zmienna hasNextPage jest równa true (3). Ta zmienna (4) przechowuje informacje o paginacji. W przypadku bowiem, gdy dyskusji będzie odpowiednio dużo, jedno zapytanie nie zwróci ich wszystkich. Wówczas wynik będzie zawierał informację o tym, że jeszcze są inne dyskusje, które trzeba pobrać (5). W tym celu wynik zawiera także kursor (6), który sobie zapisujemy (7), aby użyć go w kolejnym zapytaniu. Kursor to wskaźnik, który pokazuje, gdzie zakończyliśmy pobieranie dyskusji i pozwala kontynuować od tego miejsca. Samo zapytanie wykonujemy przy pomocy metody #graphl() z biblioteki octokit (8). Najpierw jednak musimy stworzyć klienta Ocktokit (9), przekazując mu token dostępowy (10). Gdy już wykonamy zapytanie, wyciągamy z wyniku dwie własności (11): nodes (zwrócone dyskusje) oraz pageInfo (informacje o paginacji). Zwrócone dyskusje dodajemy do tablicy discussions (12), którą na końcu zwracamy (13).

Teraz trzeba dodać wywołanie funkcji getExistingDiscussions() do istniejącej logiki:

const existingDiscussions = await getExistingDiscussions( { // 1
	owner: env.REPO_OWNER, // 2
	repo: env.REPO_NAME, // 3
	categoryId: env.CATEGORY_ID // 4
} );
const missingPosts = posts.filter( ( { slug } ) => { // 5
	return existingDiscussions.findIndex( ( { title } ) => { // 6
		return title === slug; // 7
	} ) === -1;
} );

console.log( 'Brakujących dyskusji:', missingPosts.length ); // 8

Umieszczamy ten kod po pętli pobierającej metadane wpisów. Do zmiennej existingDiscussions zapisujemy wynik funkcji getExistingDiscussions() (1). Do jej wywołania przekazujemy zmienne środowiskowe z nazwą właściciela repozytorium (2), nazwą repozytorium (3) oraz ID kategorii dyskusji (4). Następnie tworzymy tablicę (5) wpisów, dla których nie ma jeszcze dyskusji. Robimy to przy pomocy przefiltrowania tablicy wszystkich wpisów przy pomocy metody Array#findIndex(), sprawdzającej (6), czy tablica istniejących dyskusji posiada wpis dla danego sluga (7). Na końcu wyświetlamy informację, ile dyskusji brakuje (8).

Drugi etap pracy za nami, pora na trzeci!

Tworzenie brakujących dyskusji

Żeby stworzyć brakujące dyskusje, napiszemy nową funkcję, createMissingDiscussions():

async function createMissingDiscussions( options ) {
	const repositoryId = await getRepositoryId( options.owner, options.repo ); // 1

	for ( const post of options.posts ) { // 2
		await createDiscussion( { // 3
			repositoryId, // 4
			categoryId: options.categoryId, // 5
			title: post.slug, // 6
			body: createDiscussionBody( post, options.blogUrl ) // 7
		} );

		const randomSleepTime = Math.floor( Math.random() * 6 ) + 1; // 9

		await sleep( randomSleepTime ); // 8
	}
}

Na początku pobieramy ID repozytorium na podstawie jego właściciela i nazwy (1). Następnie dla każdego z przekazanych wpisów (2) wywołujemy funkcję createDiscussion() (3), której przekazujemy ID repozytorium (4), ID kategorii dyskusji (5), tytuł dyskusji, czyli w naszym wypadku sluga (6), oraz treść dyskusji, którą tworzymy przy pomocy funkcji createDiscussionBody() (7). Zanim przejdziemy do dodawania kolejnej dyskusji, odczekujemy losową liczbę sekund (8), a dokładniej – między 1 a 6 (9). Robimy to, żeby nie natknąć się na ograniczenia po stronie GitHubowego API.

Funkcja getRepositoryId() prezentuje się następująco:

async function getRepositoryId( owner, name ) {
	/* 1 */ const query = `
		query($owner: String!, $name: String!) {
			repository(owner: $owner, name: $name) {
				id
			}
		}`;

	const result = await octokit.graphql( query, { // 2
        owner, // 3
        name // 4
    } );

	return result.repository.id; // 5
}

Zawiera ono zapytanie GraphQL (1), które pobiera ID repozytorium. Wykonujemy je (2), przekazując właściciela (3) oraz nazwę repozytorium (4), a następnie zwracamy pobrane ID (5).

Funkcja createDiscussion() z kolei wygląda tak:

async function createDiscussion( options ) {
	const query = `
		mutation($input: CreateDiscussionInput!) {
			createDiscussion(input: $input) {
				discussion {
					title
				}
			}
		}`;
	const response = await octokit.graphql( query, { // 2
		input: options // 3
	} );


	console.log( `Created discussion`, response.createDiscussion.discussion.title ); // 4
}

Ona również ma w sobie zapytanie GraphQL (1) – z tym, że typu mutation zamiast query. Wykonujemy je (2), przekazując obiekt z danymi nowej dyskusji jako input (3). Na końcu wyświetlamy informację o dodanej dyskusji (4).

Dwie pomocnicze funkcje, createDiscussionBody() i sleep() prezentują się jak poniżej:

function createDiscussionBody( { slug, description }, blogUrl ) {
	const link = `${ blogUrl }${ slug }`;

	/* 1 */ return `# ${ slug }

${ description }

${ link }`;
}

async function sleep( seconds ) {
	return new Promise( ( resolve ) => {
		setTimeout( resolve, seconds * 1000 );
	} );
}

Jeśli chodzi o funkcję sleep(), to bardzo podobną funkcję tworzyliśmy dla czasomierzy. Natomiast funkcja createDiscussionBody() tworzy tekst w formacie Markdown (1) na podstawie przekazanych jej danych, a następnie go zwraca.

Ostatnim krokiem jest dodanie wywołania funkcji createMissingDiscussions() na koniec głównej logiki skryptu:

await createMissingDiscussions( {
	owner: env.REPO_OWNER, // 1
	repo: env.REPO_NAME, // 2
	categoryId: env.CATEGORY_ID, // 3
	posts: missingPosts, // 4
	blogUrl: env.BLOG_URL // 5
} );

Do wywołania przekazujemy:

1. właściciela repozytorium,
2. nazwę repozytorium,
3. ID kategorii dyskusji,
4. listę wpisów, dla których chcemy stworzyć dyskusje,
5. URL bloga, żeby móc stworzyć ładne linki w dyskusjach.

Jeśli wszystko poszło dobrze i odpalimy teraz nasz skrypt, powinien wykryć, ile wpisów nie ma swoich dyskusji i zacząć je sukcesywnie dodawać!

Całość kodu, z dodatkową dokumentacją, znaleźć można w repozytorium Comandeer/fix-discussions.

I to tyle. Zgłoszony błąd powinien zostać naprawiony!

Ścieżki

Zerknijmy na najprostszy przykład użycia Expressa. Jest tam wykorzystana jedna ścieżka:

app.get( '/', ( req, res ) => { // 1
	res.send( 'Hello World!' ); // 2
} );

Powyższy kod oznacza, że jeśli ktoś wejdzie na stronę główną, czyli ścieżkę / (1), to dostanie w odpowiedzi tekst Hello World! (2). Nazwa metody #get() również nie jest przypadkowa, bo odpowiada metodzie HTTP GET. Jeśli z kolei chcielibyśmy dodać funkcję, która obsługiwałaby wysyłkę formularza, to możemy użyć metody HTTP POST:

app.post( '/', ( req, res ) => {
	res.send( 'Hello World!' );
} );

Express obsługuje w taki sposób wszystkie najbardziej popularne metody HTTP oraz sporo mniej popularnych. Dla porządku dodam jeszcze, że parametr req to żądanie wysłane z przeglądarki, a res – odpowiedź, jaką odsyłamy.

Natomiast bohaterem dzisiejszego odcinka są ścieżki. W tym przykładzie mieliśmy do czynienia z najprostszą, /. Niemniej można tworzyć też o wiele bardziej skomplikowane, np.:

app.get( '/user/:id', ( req, res ) => {
	res.send( `User ${req.params.id}` );
} );

Ta obsługa żądań odpali się tylko dla adresów pasujących do wzoru /user/:id, a więc np. /user/100, /user/Comandeer itd. Ale już nie /user. Można też część ścieżki oznaczyć jako opcjonalną:

app.get( '/article/:id{/:title}', ( req, res ) => {
    res.send( 'Super artykuł' );
} );

Id artykułu jest wymagane, natomiast jego tytuł – już nie. Stąd ta ścieżka pasuje zarówno do adresu /article/1618/comandeer-jest-sexy, jak i /article/67.

Można też skorzystać z *, żeby zastąpić dowolną liczbę znaków, np /user/* będzie pasować do /user/Comandeer, ale też /user/to/chyba/nie/powinno/tak/dzialac.

Samymi ścieżkami, bez całej reszty Expressa, można się pobawić, instalując pakiet npm path-to-regexp. Liczba ściągnięć dobrze pokazuje, że praktycznie wszyscy z niego korzystają. Stał się na tyle dobrze zakorzenionym de facto standardem, że… powstał na jego podstawie faktyczny standard.

URLPattern

URLPattern to API standaryzowane przez WHATWG. Specyfikacja wprost zaznacza, że składnia wzorów jest oparta na bibliotece path-to-regexp. Niemniej samo API jest zdecydowanie bardziej… przeglądarkowe, Przyjrzyjmy się, w jaki sposób przenieść do URLPatternu przykład z artykułem:

const pattern = new URLPattern({ // 1
  pathname: '/article/:id{/:title}*', // 2
});

console.log( pattern.exec( '/article/1618/jakis-tytul' ) ); // null
console.log( pattern.exec( '/article/67' ) ); // null

Na początku tworzymy nowy obiekt URLPattern (1), do którego przekazujemy obiekt z opcjami. Tak naprawdę obiekt ten może mieć wszystkie własności obiektu URL – a zatem nic nie stoi na przeszkodzie, żeby np. stworzyć… walidator schematu, odrzucający URL-e bez HTTPS. W naszym przykładzie chcemy jedynie porównać samą ścieżkę URL-a (czyli to, co następuje po domenie), zatem używamy własności pathname (2). Warto zwrócić uwagę, że składnia standardu jest oparta na bibliotece path-to-regexp, ale nie jest identyczna. W tym wypadku opcjonalną grupę musimy oznaczyć dodatkowo * (jak w wyrażeniach regularnych!). Następnie taki wzorzec testujemy na dwóch ścieżkach i… dostajemy null w obydwu przypadkach.

Dzieje się tak, ponieważ URLPattern działa z URL-ami i wymaga pełnego URL-a, nie relatywnego, jak w naszym przykładzie. Można ten problem rozwiązać na trzy sposoby:

console.log( pattern.exec( 'https://blog.comandeer.pl/article/1618' ) ) // 1
console.log( pattern.exec( '/article/67', 'https://blog.comandeer.pl' ) ); // 2
console.log( pattern.exec( {
    pathname: '/article/1618/dziala' // 3
} ) );

Najbardziej oczywisty to podanie pełnego URL-a (1). Można też podać samą ścieżkę, a jako drugi argument podać tzw. bazowy URL (2). Wówczas przeglądarka sama rozwiąże pełny adres (czyli po prostu doklei ścieżkę do bazowego URL-a). W końcu można przekazać obiekt z własnością pathname (3) – czyli podobny do tego, który przekazaliśmy do konstruktora. Warto też zauważyć, że w tym przykładzie jest całkowicie nieistotne, jaką domenę dodamy do ścieżki – bo ostatecznie tylko ścieżkę chcemy porównywać.

Konstruktor również przyjmuje te trzy rodzaje opcji:

new URLPattern( {
    pathname: '/article/:id{/:title}*'
} );
// vs
new URLPattern( 'https://blog.comandeer.pl/article/:id{/:title}*' );
// vs
new URLPattern( '/article/:id{/:title}*', 'https://blog.comandeer.pl' );

W przypadku konstruktora dobrany URL ma jednak spore znaczenie. Podanie pełnego URL-a sprawi, że będzie on używany do dopasowania, więc tylko URL-e z originu https://blog.comandeer.pl będą brane pod uwagę.

Spójrzmy na rezultat metody URLPattern#exec():

{
	"hash": {
		"groups": {
			"0": ""
		},
		"input": ""
	},
	"hostname": {
		"groups": {
			"0": "blog.comandeer.pl"
		},
		"input": "blog.comandeer.pl"
	},
	"inputs": [
		"https://blog.comandeer.pl/article/1618"
	],
	"password": {
		"groups": {
			"0": ""
		},
		"input": ""
	},
	"pathname": {
		"groups": {
			"id": "1618"
		},
		"input": "/article/1618"
	},
	"port": {
		"groups": {
			"0": ""
		},
		"input": ""
	},
	"protocol": {
		"groups": {
			"0": "https"
		},
		"input": "https"
	},
	"search": {
		"groups": {
			"0": ""
		},
		"input": ""
	},
	"username": {
		"groups": {
			"0": ""
		},
		"input": ""
	}
}

Wygląda strasznie na pierwszy rzut oka, ale takie nie jest w rzeczywistości! Po raz kolejny mamy tutaj wszystkie własności URL-a. Do tego tablicę inputs, zawierającą tablicę URL-i, na których URLPattern#exec() zostało wywołane. Jeśli któryś z elementów URL-a został dopasowany, to znajduje się w odpowiedniej własności, np. hostname:

{
	"hostname": {
		"groups": {
			"0": "blog.comandeer.pl"
		},
		"input": "blog.comandeer.pl"
	}
}

Z racji tego, że domenę dopasowywaliśmy w całości, we własności groups jest tylko jedna, domyślna grupa 0, która zawiera to samo, co własność input. Natomiast we własności pathname robi się już ciekawiej:

{
	"pathname": {
		"groups": {
			"id": "1618"
		},
		"input": "/article/1618"
	}
}

We własności input wciąż jest pełne dopasowanie, niemniej pojawiła się grupa o nazwie, jaką mieliśmy we wzorze – id; A w niej: poprawnie dopasowany id artykułu!

I tak, porównując to do ścieżek w Expressie, wydaje się to wszystko niepotrzebnie skomplikowane. I prawdopodobnie takie jest. Ale nie można zapominać przy tym, że to musi się dobrze wpisywać w ekosystem przeglądarki, w której URL-e istnieją od zawsze. I każdy nowy element musi pasować do tych już istniejących. Dodatkowo, myślę, że URLPattern można z powodzeniem zaliczyć do tych niskopoziomowych API, które niekoniecznie warto używać bezpośrednio, ale warto na nich budować swoje własne rozwiązania.

No i umyślnie w przypadku URLPatternu używałem terminu “wzorzec” zamiast “ścieżka” (tę zostawiając dla URL-i). Dzięki temu, że URLPattern dopasowuje całe URL-e, można go zastosować do wielu innych rzeczy, niż tylko do ścieżek (jak np. wspomniany wyżej walidator). Zresztą to API oryginalnie powstało na potrzeby Service Workerów, przy okazji rozwiązując też inne problemy.

Prymitywny Express.js

Choć URLPattern zaczynał jako API przeglądarkowe, to obecnie jest dostępny także w środowiskach backendowych – w tym w Node.js (od wersji 23). A to oznacza, że można go wykorzystać do stworzenia własnej wersji Express.js!

Na początku stwórzmy plik server.mjs, z którego wyeksportujemy odpowiednik funkcji express() – funkcję server():

export function server() {}

Funkcja ta zwróci obiekt z API naszego “frameworka”:

export function server() {
	return {
		get() { // 1
			return this; // 4
		},
		post() { // 2
			return this; // 5
		},
		listen() { // 3
			return this; // 6
		}
	};
};

Nasz framework będzie miał tylko trzy metody – #get() (1) do obsługi żądań GET, #post() (2) do obsługi żądań POST oraz #listen() (3) do odpalenia serwera na wybranym porcie. Każda z funkcji zwraca this (4, 5, 6), dzięki czemu można tworzyć łańcuchy wywołań.

Żeby jednak móc odpalić serwer, trzeba najpierw go mieć. Tutaj na ratunek przychodzi wbudowany w Node moduł node:http:

import { createServer } from 'node:http'; // 1

export function server() {
	const server = createServer(); // 2

	return {
		get() {
			return this;
		},
		post() {
			return this;
		},
		listen( port = 3000 ) {
			server.listen( port ); // 3

			return this;
		}
	};
};

Na początku importujemy funkcję createServer() z modułu node:http (1). Następnie tworzymy przy jej pomocy nowy serwer (2), a następnie w metodzie #listen() odpalamy go na podanym porcie (3).

Niemniej serwer, który nic nie robi, jest mało użyteczny. Dodajmy zatem obsługę żądań:

[…]
export function server() {
	const server = createServer();
	const handlers = []; // 3

	server.on( 'request', ( request, response ) => { // 1
		for ( const handler of handlers ) { // 2
			if ( handler( request, response ) ) { // 4
				return; // 5
			}
		}

		response.writeHead( 404 ); // 6
		response.end(); // 7
	} );

    […]
}

Do naszego serwera dodajemy obsługę zdarzenia request (1). Nasłuchiwacz dostaje dwa argumenty: żądanie (request) oraz odpowiedź (response). Zatem bardzo podobnie do tego, jak działa to w Express.js. Iterujemy po wszystkich handlerach (2) w tablicy handlers (3) i wywołujemy każdy, przekazując do niego żądanie i odpowiedź (4). Jeśli handler zwróci true, kończymy całą obsługę żądania (5). Natomiast jeśli obsługa nie zostanie zakończona w tym miejscu, to znak, że żaden handler nie obsłużył żądania (nie zwrócił true). Dlatego też ustawiamy status 404 przy pomocy metody response#writeHead() (6), a następnie wysyłamy pustą odpowiedź przy pomocy metody response#end() (7).

W tym momencie serwer dla dowolnego żądania zwróci błąd 404. Nie jest to mocno użyteczne, więc wypada dodać dodawanie handlerów:

[…]

export function server() {
	[…]

	return {
		get( path, handler ) {
			const internalHandler = createHandler( 'GET', path, handler ); // 1

			handlers.push( internalHandler ); // 3

			return this;
		},
		post( path, handler ) {
			const internalHandler = createHandler( 'POST', path, handler ); // 2

			handlers.push( internalHandler ); // 4

			return this;
		}

		[…]
	};
}

W metodach #get() i #post() pojawiły się wywołania funkcji createHandler() (1, 2). Tak powstałe handlery są następnie dodawane do tablicy handlers (3, 4).

Sama funkcja createHandler() wygląda z kolei tak:

function createHandler( method, path, handler ) { // 1
	const pattern = new URLPattern( { // 2
		pathname: path // 3
	} );

	return ( request, response ) => { // 4
		if ( request.method !== method ) { // 5
			return false; // 6
		}

		const matchedUrl = pattern.exec( request.url ); // 7

		if ( matchedUrl === null ) { // 8
			return false; // 9
		}

		handler( toHandlerRequest( request. matchedUrl ), toHandlerResponse( response ) ); // 10

		return true;
	};
}

function toHandlerRequest( request, matchedUrl ) {
	return {
		url: request.url, // 11
		params: matchedUrl.pathname.groups // 12
	};
}

function toHandlerResponse( response ) {
	return {
		send( content ) { // 13
			response.writeHead( 200, { 'Content-Type': 'application/json' } ); // 14
			response.end( JSON.stringify( content ) ); // 15
		}
	};
}

Funkcja przyjmuje trzy parametry (1):

1. method – nazwę metody HTTP (w tym przypadku GET albo POST),
2. path – ścieżkę,
3. handler – funkcję do obsługi żądania.

Następnie tworzymy nowy URLPattern (2) i przekazujemy do niego naszą ścieżkę (3). Potem tworzymy funkcję, którą na koniec zwrócimy (4). Przyjmuje ona dwa parametry: żądanie (request) oraz odpowiedź (response). Wewnątrz tej funkcji na samym początku sprawdzamy, czy żądanie przyszło przy pomocy interesującej nas metody (5). Jeśli nie, kończymy obsługę tego żądania i zwracamy false (6). Jeśli tak, dopasowujemy URL żądania do naszego wzorca (7). Jeśli nie udało się dopasować (8), kończymy obsługę żądania i zwracamy false (9). Dzięki tym dwóm sprawdzeniom jesteśmy w stanie poprawnie obsługiwać błędy 404 w głównym nasłuchiwaczu serwera. Jeśli żądanie zostało dopasowane, wywołujemy przekazany handler() (10) wraz ze specjalnie spreparowanymi żądaniem i odpowiedzią.

Żądanie, jakie dostanie handler, ma tak naprawdę tylko dwie własności – oryginalny URL (11) jako url oraz dopasowane grupy (12) jako params. Z kolei odpowiedź ma tylko jedną metodę, #send() (13), która przyjmuje jeden parametr – zawartość odpowiedzi (content). Ta metoda ustawia status 200 oraz nagłówek Content-Type na application/json , sygnalizując, że odpowiedź będzie JSON-em (14). Następnie serializuje content i wysyła tak powstały ciąg znaków do przeglądarki (15).

Pora przetestować nasz serwer! Stwórzmy w tym celu plik app.mjs:

import { server } from './server.mjs'; // 1

const app = server(); // 2

app.get( '/', ( request, response ) => { // 3
	response.send( {
		version: '1.0.0' // 4
	} );
} );
app.get( '/user/:id', ( request, response ) => { // 5
	response.send( {
		id: request.params.id // 6
	} );
} );

app.listen( 3000 ); // 7
console.log( 'Server is listening on port 3000' ); // 8

Na początku importujemy funkcję server() z pliku ./server.mjs (1). Następnie tworzymy nowy serwer i przypisujemy go do zmiennej app (2). Potem dodajemy obsługę żądań do strony głównej, / (3). W odpowiedzi wysyłamy obiekt z wersją naszego “API” (4). Potem dodajemy obsługę dla ścieżki /user/:id (5). Żeby przetestować, czy ich obsługa działa poprawnie, zwracamy przekazany parametr id (6). Na sam koniec odpalamy serwer na porcie 3000 (7) oraz wyświetlamy w konsoli informację, że serwer działa (8).

Teraz można odpalić serwer:

node ./app.mjs

A następnie przejść do przeglądarki i sprawdzić, czy dostaniemy poprawną odpowiedź. Jeśli wejdziemy pod adres http://localhost:3000, to powinniśmy otrzymać:

{
	"version": "1.0.0"
}

Natomiast jeśli wejdziemy pod adres http://localhost:3000/user/Comandeer, powinniśmy otrzymać:

{
	"id": "Comandeer"
}

Jeśli wpiszemy dowolny nieobsługiwany adres (np. http://localhost:3000/whatever), przeglądarka powinna wyświetlić domyślny błąd 404.

Całość kodu, wraz z dokumentacją w formacie JSDoc, znajduje się w Giście.