Lock

Moduł Lock zapewnia dostęp do mechanizmu rozproszonego blokowania (distributed locking) zarządzanego przez platformę Orbito. Pozwala na upewnienie się, że konkretna operacja jest wykonywana tylko raz, nawet gdy równolegle działa wiele procesów modułu.

const { Core } = require('@orbito/api-lib');

Zasięg blokady

lockId jest surowy i musi być unikalny wyłącznie w obrębie Twojej instalacji modułu — platforma sama prefiksuje go identyfikatorem instancji. Nie doklejaj do niego companyId ani instanceId: blokady nigdy nie kolidują z innymi firmami ani z innymi instalacjami tego samego modułu (np. dwa sklepy mogą równolegle trzymać blokadę order:process:123).

getLock

Uzyskuje rozproszoną blokadę, która zapewnia, że określona operacja jest wykonywana tylko raz, nawet gdy równolegle działa wiele procesów modułu. Zwraca null, jeśli blokada jest już zajęta.

const lockId = await Core.getLock(lockId, ttl);

Parametr	Typ	Opis
`lockId`	`string`	Unikalny identyfikator blokady (np. `"order:process:123"`)
`ttl`	`number`	Czas życia blokady w milisekundach po którym blokada automatycznie wygasa

const lockId = await Core.getLock("order:process:123", 5000);
if (!lockId) return; // ktoś inny już obsługuje to zamówienie
try {
    // sekcja krytyczna – wykonywana przez jeden proces jednocześnie
} finally {
    await Core.releaseLock(lockId);
}

extendLockTime

Przedłuża czas życia już nabytej blokady. Używaj tego do zapobiegania wygaśnięciu blokady podczas długotrwałej operacji bez wcześniejszego jej zwalniania.

await Core.extendLockTime(lockId, ttl);

Parametr	Typ	Opis
`lockId`	`string`	Identyfikator blokady do przedłużenia (taki sam jak zwrócony przez `getLock`)
`ttl`	`number`	Nowy czas życia w milisekundach od momentu przedłużenia

await Core.extendLockTime("order:process:123", 5000);

releaseLock

Zwalnia wcześniej nabytą blokadę, umożliwiając jej uzyskanie kolejnemu procesowi. Zawsze powinno być wywoływane po zakończeniu sekcji krytycznej (idealnie w bloku finally).

await Core.releaseLock(lockId);

Parametr	Typ	Opis
`lockId`	`string`	Identyfikator blokady do zwolnienia (taki sam jak zwrócony przez `getLock`)

await Core.releaseLock("order:process:123");

Zasada działania

Mechanizm blokady działa na zasadzie unikalnego identyfikatora (lockId) i czasu życia (ttl). Jeśli proces próbuje uzyskać blokadę, która już istnieje i nie wygasła, otrzymuje wartość null. Po zakończeniu operacji blokada musi zostać zwolniona, aby pozostałe procesy mogły kontynuować pracę.

Niebezpieczeństwo zakleszczenia

Upewnij się, że zawsze wywołujesz releaseLock w bloku finally, nawet jeśli operacja zakończy się błędem. W przeciwnym razie blokada może zostać zablokowana na zawsze.