Labeler

De Labeler is een functie voor gevorderden. Omdat deze continu als server moet draaien, is dit bedoeld voor wie Laravel Forge gebruikt of zelf een server kan opzetten. Niet aanbevolen voor Laravel-beginners. Er is geen ondersteuning.Laravel Cloud wordt niet ondersteund. Een Labeler moet permanent draaien als WebSocket-server en vereist aanpassingen aan de nginx-configuratie, maar op Laravel Cloud kun je nginx niet configureren, dus daar kan een Labeler niet draaien.

Wat is een Labeler?

Een Labeler is een service die labels toekent aan content op het AT Protocol (Bluesky). Je kunt hem inzetten voor moderatie, contentclassificatie, eigen filters en meer. Het is nodig dat je vooraf het concept van een Labeler begrijpt.

Starter kits voor andere talen zijn ook nuttig als referentie.

Voorbeeldimplementaties:

Voorbereiding

Om een Labeler te draaien heb je het volgende nodig.

Een nieuw Bluesky-account speciaal voor de Labeler (gebruik niet je dagelijkse account)
Een nieuw Laravel-project speciaal voor de Labeler (aparte projecten worden aanbevolen)
Een (sub)domein
Een productie-Linux-server zoals een VPS of AWS EC2 (Laravel Cloud, Laravel Vapor en Vercel zijn niet mogelijk)

Als je alleen shared hosting kunt gebruiken, is het lastig om een Labeler te draaien.

Extra pakketten installeren

composer require workerman/workerman revolt/event-loop

Configuratie

Genereer eerst een privésleutel.

php artisan bluesky:labeler:new-private-key

Voeg de gegenereerde privésleutel en de bijbehorende configuratiewaarden toe aan .env.

BLUESKY_LABELER_DID=did:plc:***
BLUESKY_LABELER_IDENTIFIER=***.bsky.social
BLUESKY_LABELER_APP_PASSWORD=

BLUESKY_LABELER_PRIVATE_KEY=""

Een Labeler-klasse maken

Maak een eigen Labeler-klasse die erft van AbstractLabeler. Het bestand mag op een willekeurige plek staan.

namespace App\Labeler;

use Revolution\Bluesky\Labeler\AbstractLabeler;

readonly class ArtisanLabeler extends AbstractLabeler
{
    // Implementeer de afzonderlijke methods
}

Het pakket neemt het grootste deel van de Labeler-verwerking voor zijn rekening, dus je implementeert alleen de onderdelen die je wilt aanpassen.

Voorbeeldimplementatie: ArtisanLabeler.php

labels()

Geeft de labeldefinities terug. De constantedefinities in de skyware-starterkit zijn een goede referentie.

use Revolution\Bluesky\Labeler\LabelDefinition;
use Revolution\Bluesky\Labeler\LabelLocale;

public function labels(): array
{
    return [
        new LabelDefinition(
            identifier: 'artisan',
            locales: [
                new LabelLocale(
                    lang: 'en',
                    name: 'artisan',
                    description: 'Web artisan',
                ),
            ],
            severity: 'inform',
            blurs: 'none',
            defaultSetting: 'warn',
            adultOnly: false,
        ),
    ];
}

subscribeLabels()

Wordt direct na het opzetten van de WebSocket-verbinding aangeroepen. Geeft SubscribeLabelResponse-objecten terug als iterator.

use Revolution\Bluesky\Labeler\Labeler;
use Revolution\Bluesky\Labeler\LabelerException;
use Revolution\Bluesky\Labeler\Response\SubscribeLabelResponse;

/**
 * @return iterable<SubscribeLabelResponse>
 */
public function subscribeLabels(?int $cursor): iterable
{
    if (is_null($cursor)) {
        return null;
    }

    // Gooi altijd een LabelerException als je een foutresponse wilt teruggeven
    if ($cursor > Label::max('id')) {
        throw new LabelerException('FutureCursor', 'Cursor is in the future');
    }

    foreach (Label::oldest()->where('id', '>', $cursor)->lazy() as $label) {
        $arr = $label->toArray();
        $arr = Labeler::formatLabel($arr);

        yield new SubscribeLabelResponse(
            seq: $label->id,
            labels: [$arr],
        );
    }
}

emitEvent()

Wordt aangeroepen wanneer er een request binnenkomt om een label toe te voegen of te verwijderen. Geeft UnsignedLabel-objecten terug als iterator.

use Illuminate\Http\Request;
use Revolution\Bluesky\Labeler\LabelerException;
use Revolution\Bluesky\Labeler\UnsignedLabel;

/**
 * @return iterable<UnsignedLabel>
 *
 * @link https://docs.bsky.app/docs/api/tools-ozone-moderation-emit-event
 */
public function emitEvent(Request $request, ?string $did, ?string $token): iterable
{
    $type = data_get($request->input('event'), '$type');
    if ($type !== 'tools.ozone.moderation.defs#modEventLabel') {
        throw new LabelerException('InvalidRequest', 'Unsupported event type');
    }

    $subject = $request->input('subject');
    $uri = data_get($subject, 'uri', data_get($subject, 'did'));
    $cid = data_get($subject, 'cid');

    $createLabelVals = (array) data_get($request->input('event'), 'createLabelVals');
    $negateLabelVals = (array) data_get($request->input('event'), 'negateLabelVals');

    foreach ($createLabelVals as $val) {
        yield new UnsignedLabel(
            uri: $uri,
            cid: $cid,
            val: $val,
            src: config('bluesky.labeler.did'),
            cts: now()->micro(0)->toISOString(),
        );
    }

    foreach ($negateLabelVals as $val) {
        yield new UnsignedLabel(
            uri: $uri,
            cid: $cid,
            val: $val,
            src: config('bluesky.labeler.did'),
            cts: now()->micro(0)->toISOString(),
            neg: true,
        );
    }
}

saveLabel()

Slaat het ondertekende label op in de database. Geeft een SavedLabel terug.

use Revolution\Bluesky\Labeler\SavedLabel;
use Revolution\Bluesky\Labeler\SignedLabel;

public function saveLabel(SignedLabel $signed, string $sign): ?SavedLabel
{
    // App\Models\Label maak je zelf aan
    $saved = Label::create($signed->toArray());

    return new SavedLabel(
        $saved->id,
        $signed,
    );
}

Raadpleeg voor de migratie en het Eloquent-model de voorbeelden in het pakket.

createReport()

Wordt aangeroepen wanneer een gebruiker bijvoorbeeld een appeal instuurt.

use Illuminate\Http\Request;

/**
 * @link https://docs.bsky.app/docs/api/com-atproto-moderation-create-report
 */
public function createReport(Request $request): array
{
    // Verwerk de report en geef een array terug
    // Verplichte velden: id, reasonType, reason, subject, reportedBy, createdAt

    return [
        'id' => 1,
        'reasonType' => $request->input('reasonType'),
        'reason' => $request->input('reason', ''),
        'subject' => $request->input('subject'),
        'reportedBy' => '',
        'createdAt' => now()->toISOString(),
    ];
}

queryLabels()

Query’t labels via de HTTP-API in plaats van WebSocket. Wordt niet gebruikt door het officiële Bluesky, maar door derde partijen. Geef een lege array terug als je dit niet nodig hebt.

use Illuminate\Http\Request;

/**
 * @link https://docs.bsky.app/docs/api/com-atproto-label-query-labels
 */
public function queryLabels(Request $request): array
{
    return [];
}

Registreren in de AppServiceProvider

Registreer de gemaakte Labeler-klasse in AppServiceProvider::boot().

use Revolution\Bluesky\Labeler\Labeler;
use App\Labeler\ArtisanLabeler;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Labeler::register(ArtisanLabeler::class);
    }
}

Het account instellen

Initialiseer het account als Labeler-account.

Bij dit command voer je niet het app-wachtwoord in maar het echte accountwachtwoord. Tijdens het proces ontvang je een bevestigingsmail met “PLC Update Operation Requested”; volg de instructies van het command om de code in te voeren.

php artisan bluesky:labeler:setup

Als de endpoint-URL correct is ingesteld, kun je dit ook vanuit je lokale omgeving uitvoeren.

Labeldefinities declareren

Registreer de labeldefinities bij het Labeler-account.

php artisan bluesky:labeler:declare-labels

Ook dit command kun je vanuit je lokale omgeving uitvoeren.

Overige commands

Labeldefinities verwijderen:

php artisan bluesky:labeler:delete-labels

Het Labeler-account terugzetten naar een gewoon account:

php artisan bluesky:labeler:restore

Draaien op Laravel Forge

Start na het inschakelen van SSL de Labeler-server met de volgende configuratie.

nginx-configuratie

Voeg drie location-blokken toe aan de nginx-configuratie van Forge.

# WebSocket: labelabonnement
location /xrpc/com.atproto.label.subscribeLabels
{
    proxy_pass http://127.0.0.1:7000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header X-Real-IP $remote_addr;
}

# HTTP: events versturen
location /xrpc/tools.ozone.moderation.emitEvent
{
    proxy_pass http://127.0.0.1:7001;
    proxy_http_version 1.1;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Connection "";
}

# Healthcheck
location /xrpc/_health
{
    proxy_pass http://127.0.0.1:7001;
    proxy_http_version 1.1;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Connection "";
}

Deployscript

Stop de Labeler-server tijdens het deployen. Na het stoppen herstart Supervisor deze automatisch.

# De gebruikelijke deploystappen
$FORGE_PHP artisan bluesky:labeler:server stop

# Als het bovenstaande niet werkt, herstart de daemon dan rechtstreeks
sudo -S supervisorctl restart daemon-{id}:*

Achtergrondproces (daemon) instellen

Kies in het scherm voor achtergrondprocessen van Forge het tabblad Custom in plaats van het tabblad Queue Worker. Command:

php artisan bluesky:labeler:server start

Geef opties op als je tegelijk met Jetstream of de Firehose wilt starten. Gelijktijdig draaien met de commands bluesky:ws of bluesky:firehose is niet mogelijk.

# Samen met Jetstream starten
php artisan bluesky:labeler:server start --jetstream

# Specifieke collecties filteren
php artisan bluesky:labeler:server start --jetstream -C app.bsky.graph.follow -C app.bsky.feed.like

# Samen met de Firehose starten
php artisan bluesky:labeler:server start --firehose

Labels toevoegen

Hoe je labels toekent, hangt af van de implementatie van je applicatie. In het voorbeeld wordt de eventfunctionaliteit van Laravel gebruikt om een label toe te kennen “wanneer iemand je volgt”.

// Zoals in app/Listeners/FollowListener.php

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Events\Jetstream\JetstreamCommitMessage;
use Revolution\Bluesky\Types\RepoRef;

public function handle(JetstreamCommitMessage $event): void
{
    $message = $event->message;
    $followerDid = data_get($message, 'did');

    // Een label toekennen via de Ozone-API van Bluesky
    Bluesky::login(
        identifier: config('bluesky.labeler.identifier'),
        password: config('bluesky.labeler.password'),
    )->createLabels(
        subject: RepoRef::to($followerDid),
        labels: ['artisan'],
    );
}

Het wordt aanbevolen om ook via de task scheduler labels toe te kennen, voor het geval er events gemist worden.

Source: docs/labeler.md Sample: invokable/laralabeler

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds en RSS

Middleware

Wat is een Labeler?

Voorbereiding

Extra pakketten installeren

Configuratie

Een Labeler-klasse maken

labels()

subscribeLabels()

emitEvent()

saveLabel()

createReport()

queryLabels()

Registreren in de AppServiceProvider

Het account instellen

Labeldefinities declareren

Overige commands

Draaien op Laravel Forge

nginx-configuratie

Deployscript

Achtergrondproces (daemon) instellen

Labels toevoegen

​Wat is een Labeler?

​Voorbereiding

​Extra pakketten installeren

​Configuratie

​Een Labeler-klasse maken

​labels()

​subscribeLabels()

​emitEvent()

​saveLabel()

​createReport()

​queryLabels()

​Registreren in de AppServiceProvider

​Het account instellen

​Labeldefinities declareren

​Overige commands

​Draaien op Laravel Forge

​nginx-configuratie

​Deployscript

​Achtergrondproces (daemon) instellen

​Labels toevoegen

Wat is een Labeler?

Voorbereiding

Extra pakketten installeren

Configuratie

Een Labeler-klasse maken

labels()

subscribeLabels()

emitEvent()

saveLabel()

createReport()

queryLabels()

Registreren in de AppServiceProvider

Het account instellen

Labeldefinities declareren

Overige commands

Draaien op Laravel Forge

nginx-configuratie

Deployscript

Achtergrondproces (daemon) instellen

Labels toevoegen