Adnotacje licencyjne

beanguard-client udostępnia cztery adnotacje z pakietu dev.beanguard.client.annotations do deklaratywnego zabezpieczania metod Spring Boot na podstawie treści aktywnej licencji.

@RequiresValidLicence

Blokuje metodę, jeśli aktualna licencja nie jest ważna:

import dev.beanguard.client.annotations.RequiresValidLicence;

@RequiresValidLicence
public void exportReport() {
    // wykonuje się tylko przy ważnej licencji
}

Rzuca dev.beanguard.client.exceptions.MissingOrInvalidLicence (bez wiadomości), jeśli LicenceRegistry.getStatus().isValid() zwraca false.

@RequiresLicenceFeature

Blokuje metodę, jeśli licencja nie zawiera w claims flagi o podanej nazwie ustawionej na "true":

import dev.beanguard.client.annotations.RequiresLicenceFeature;

@RequiresLicenceFeature("advanced-reports")
public void generateAdvancedReport() {
    // wymaga claims["advanced-reports"] == "true"
}

Rzuca MissingLicenceFeature z nazwą brakującej funkcji jako komunikatem — zarówno przy nieważnej licencji, jak i braku wpisu lub wartości "false" danej flagi.

@RequiresLicenceLimit

Sprawdza, czy bieżące użycie danego limitu (śledzone przez UsageRegistry) nie osiągnęło jeszcze wartości z licencji, a po wykonaniu metody zwiększa licznik użycia o 1:

import dev.beanguard.client.annotations.RequiresLicenceLimit;

@RequiresLicenceLimit("active-users")
public void createUser(UserRequest request) {
    // wykonuje się tylko, gdy usage < limit z claims["active-users"]
    // po wykonaniu: usage rośnie o 1
}

Limit to liczba całkowita zapisana jako string w claims (np. claims["active-users"] = "10") — brak wpisu w claims traktowany jest jak limit 0. Przekroczenie rzuca LicenceLimitExceeded z komunikatem w formacie "<nazwa>:<aktualne użycie>:<limit>".

@DecreasesLicenceLimit

Zmniejsza licznik użycia danego limitu po wykonaniu metody — użyj przy usuwaniu zasobu liczonego przez @RequiresLicenceLimit:

import dev.beanguard.client.annotations.DecreasesLicenceLimit;

@DecreasesLicenceLimit("active-users")
public void deleteUser(UUID userId) {
    // po wykonaniu: usage maleje o 1
}

Nazwa limitu/funkcji ("active-users", "advanced-reports") to dowolny string, który sam wybierasz — musi się tylko zgadzać z kluczem w claims licencji. Ten sam string wpisujesz jako pole Claim przy produkcie w sklepie albo bezpośrednio w tabeli claims przy ręcznym dodawaniu lub edycji licencji w panelu admina.

Śledzenie użycia limitów

Domyślnie UsageRegistry liczy użycie w pamięci — licznik resetuje się przy restarcie aplikacji. Jeśli potrzebujesz trwałego licznika (np. w bazie danych), dostarcz własny bean implementujący dev.beanguard.client.usage.UsageRegistry. To jedyny, obok BeanGuardConfiguration, interfejs pozostawiony nieobfuskowany w beanguard-client, więc możesz go bezpiecznie zaimplementować we własnym kodzie.

Obsługa wyjątków

Wszystkie trzy wyjątki — MissingOrInvalidLicence, MissingLicenceFeature, LicenceLimitExceeded — to RuntimeException rzucane w Twojej aplikacji. Przechwyć je własnym @ControllerAdvice lub podobnym mechanizmem, żeby zwrócić użytkownikowi czytelny komunikat zamiast błędu 500.