Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions KNOWLEDGE_BASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -596,6 +596,7 @@ A signed request sees what the web shows you, such as your own pending commits a
- read the hot topics, and each one's commits from the past week with its recap;
- list guilds as the Guilds page does, 24 a page, searched by name, handle or description, with whether you joined or muted each one and whether it is paused, while guilds are available to you;
- read a guild's board as its page does, 30 threads a page with reply previews, with the guild, its pinned commit and whether you moderate it, while guilds are available to you. The pinned commit also keeps its place in the list, so an app that shows it apart skips it there by its id;
- list the guilds you joined as the left navigation does, with the commits you missed in each and when that count starts, and mark a guild read as opening its board does, sharing the web's limit of 120 a minute;
- star or unstar, and list who starred your own commit, newest first, 20 a page;
- create polls on commits that are neither replies nor quotes, and vote on polls;
- change Remotes settings, read and send messages with images, link cards, and voice notes in conversations and orgs, mark them pulled, react to messages and list your reactions, pin and unpin org messages as a maintainer, find people, and start orgs;
Expand Down
26 changes: 26 additions & 0 deletions app/Http/Controllers/Api/GuildReadController.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api;

use App\Actions\UpdateGuildRead;
use App\Http\Requests\UpdateApiGuildReadRequest;
use App\Models\Guild;
use App\Models\User;
use Illuminate\Container\Attributes\CurrentUser;
use Illuminate\Http\Response;

final readonly class GuildReadController
{
/**
* Opening a board clears its missed commits, as the web's board does. A guild the user did not join has nothing
* to clear, so it writes nothing.
*/
public function update(UpdateApiGuildReadRequest $request, Guild $guild, #[CurrentUser] User $user, UpdateGuildRead $action): Response
{
$action->handle($user, $guild);

return response()->noContent();
}
}
27 changes: 27 additions & 0 deletions app/Http/Controllers/Api/JoinedGuildController.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api;

use App\Http\Requests\ListApiJoinedGuildsRequest;
use App\Models\User;
use App\Queries\JoinedGuildsQuery;
use Illuminate\Container\Attributes\CurrentUser;
use Illuminate\Http\JsonResponse;

final readonly class JoinedGuildController
{
/**
* The guilds the user joined and did not mute, as the web's left navigation lists them: the most missed commits
* first. read_from is when the count starts, the last visit to the board or the join, so a board can mark where
* the commits that are new since then end.
*/
public function index(ListApiJoinedGuildsRequest $request, #[CurrentUser] User $user, JoinedGuildsQuery $guilds): JsonResponse
{
return response()->json(['data' => array_map(fn (array $guild): array => [
...$guild,
'html_url' => route('guild.show', $guild['handle']),
], $guilds->get($user, apiIcons: true))]);
}
}
24 changes: 24 additions & 0 deletions app/Http/Requests/ListApiJoinedGuildsRequest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php

declare(strict_types=1);

namespace App\Http\Requests;

use App\Enums\Feature;
use App\Services\Features;
use Illuminate\Auth\Access\Response;
use Illuminate\Foundation\Http\FormRequest;

final class ListApiJoinedGuildsRequest extends FormRequest
{
public function authorize(Features $features): Response
{
return $features->available(Feature::Guilds, $this->user()) ? Response::allow() : Response::denyAsNotFound();
}

/** @return array{} */
public function rules(): array
{
return [];
}
}
24 changes: 24 additions & 0 deletions app/Http/Requests/UpdateApiGuildReadRequest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php

declare(strict_types=1);

namespace App\Http\Requests;

use App\Enums\Feature;
use App\Services\Features;
use Illuminate\Auth\Access\Response;
use Illuminate\Foundation\Http\FormRequest;

final class UpdateApiGuildReadRequest extends FormRequest
{
public function authorize(Features $features): Response
{
return $features->available(Feature::Guilds, $this->user()) ? Response::allow() : Response::denyAsNotFound();
}

/** @return array{} */
public function rules(): array
{
return [];
}
}
15 changes: 10 additions & 5 deletions app/Queries/JoinedGuildsQuery.php
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
use Illuminate\Support\Facades\DB;

/**
* @phpstan-type JoinedGuild array{handle: string, name: string, emoji: string, icon_url: string|null, missed_commits: int}
* @phpstan-type JoinedGuild array{handle: string, name: string, emoji: string, icon_url: string|null, missed_commits: int, read_from: string}
*/
final readonly class JoinedGuildsQuery
{
Expand All @@ -30,8 +30,12 @@ public function __construct(private Features $features, private Hashtags $hashta
//
}

/** @return list<JoinedGuild> */
public function get(User $user): array
/**
* With apiIcons, icon_url is the signed URL API clients load the icon from, as they send no web session.
*
* @return list<JoinedGuild>
*/
public function get(User $user, bool $apiIcons = false): array
{
if (! $this->features->available(Feature::Guilds, $user)) {
return [];
Expand All @@ -52,16 +56,17 @@ public function get(User $user): array
]);

return array_values($guilds
->map(function (Guild $guild) use ($commits, $readFrom): array {
->map(function (Guild $guild) use ($commits, $readFrom, $user, $apiIcons): array {
$guildReadFrom = CarbonImmutable::parse($readFrom[$guild->id]);

return [
'handle' => $guild->handle,
'name' => $guild->name,
'emoji' => $guild->emoji,
'icon_url' => $guild->iconUrl(),
'icon_url' => $apiIcons ? $guild->apiIconUrl($user) : $guild->iconUrl(),
'missed_commits' => $commits->filter(fn (array $commit): bool => $this->isPostedIn($guild, $commit)
&& $commit['created_at']->greaterThan($guildReadFrom))->count(),
'read_from' => $guildReadFrom->toIso8601ZuluString(),
];
})
->sortBy([
Expand Down
8 changes: 8 additions & 0 deletions routes/api.php
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,11 @@
use App\Http\Controllers\Api\DevicePushTokenController;
use App\Http\Controllers\Api\GuildController;
use App\Http\Controllers\Api\GuildIconController;
use App\Http\Controllers\Api\GuildReadController;
use App\Http\Controllers\Api\HeadlineController;
use App\Http\Controllers\Api\IssueController;
use App\Http\Controllers\Api\IssueSuggestionController;
use App\Http\Controllers\Api\JoinedGuildController;
use App\Http\Controllers\Api\LiveFollowingController;
use App\Http\Controllers\Api\LogController;
use App\Http\Controllers\Api\MentionSuggestionController;
Expand Down Expand Up @@ -245,6 +247,12 @@
Route::get('guilds', [GuildController::class, 'index'])->name('api-guild.index');
Route::get('guilds/{guild:handle}', [GuildController::class, 'show'])->name('api-guild.show');

// Joined guilds: the ones the web's left navigation lists, with the number of commits missed since the last visit...
Route::get('me/guilds', [JoinedGuildController::class, 'index'])->name('api-joined-guild.index');
Route::put('guilds/{guild:handle}/read', [GuildReadController::class, 'update'])
->middleware('throttle:120,1,guild-reads:')
->name('api-guild-read.update');

// Composer suggestions: people to mention and /dev/null issues to reference, as the web's composer suggests them...
Route::get('search/mentions', [MentionSuggestionController::class, 'index'])
->middleware('throttle:people')
Expand Down
2 changes: 1 addition & 1 deletion routes/web.php
Original file line number Diff line number Diff line change
Expand Up @@ -383,7 +383,7 @@
->whereUuid('commit')->withTrashed()->middleware('throttle:pins')->name('guild-commit-pin.update');
Route::put('guild-memberships/{guild}', [GuildMembershipController::class, 'update'])->whereUuid('guild')->middleware('throttle:follows')->name('guild-membership.update');
Route::put('guild-mutes/{guild}', [GuildMuteController::class, 'update'])->whereUuid('guild')->middleware('throttle:follows')->name('guild-mute.update');
Route::put('guild-reads/{guild}', [GuildReadController::class, 'update'])->whereUuid('guild')->middleware('throttle:120,1')->name('guild-read.update');
Route::put('guild-reads/{guild}', [GuildReadController::class, 'update'])->whereUuid('guild')->middleware('throttle:120,1,guild-reads:')->name('guild-read.update');
Route::post('guild-reports/{guild}', [GuildReportController::class, 'store'])->whereUuid('guild')->middleware('throttle:10,1')->name('guild-report.store');
});

Expand Down
69 changes: 69 additions & 0 deletions tests/Feature/Controllers/Api/GuildReadControllerTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
<?php

declare(strict_types=1);

use App\Enums\Feature;
use App\Enums\UserUpdate;
use App\Events\UsersUpdated;
use App\Models\Commit;
use App\Models\Guild;
use App\Models\User;
use App\Services\Features;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;

beforeEach(function (): void {
resolve(Features::class)->update(Feature::Guilds, true, adminOnly: false);
$this->travelTo('2026-11-18 12:00:00');

$this->user = User::factory()->create();
$this->keyPair = apiKeyPairFor($this->user);
$this->guild = Guild::factory()->create(['handle' => 'rust']);
});

it('marks a joined guild read, clears its missed commits and tells the other clients of the user', function (): void {
DB::table('guild_preferences')->insert(['user_id' => $this->user->id, 'guild_id' => $this->guild->id, 'joined_at' => '2026-11-01 00:00:00']);
Commit::factory()->for(User::factory())->create(['guild_id' => $this->guild->id, 'created_at' => '2026-11-18 11:00:00']);

signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index'))->assertJsonPath('data.0.missed_commits', 1);

Event::fake([UsersUpdated::class]);

signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'rust'))->assertNoContent();

expect(DB::table('guild_preferences')->where('user_id', $this->user->id)->value('read_at'))->toBe('2026-11-18 12:00:00');
Event::assertDispatched(UsersUpdated::class, fn (UsersUpdated $event): bool => $event->update === UserUpdate::Guilds && $event->userIds === [$this->user->id]);

signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index'))
->assertJsonPath('data.0.missed_commits', 0)
->assertJsonPath('data.0.read_from', '2026-11-18T12:00:00Z');
});

it('writes nothing for a guild the user did not join', function (): void {
Event::fake([UsersUpdated::class]);

signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'rust'))->assertNoContent();

expect(DB::table('guild_preferences')->count())->toBe(0);
Event::assertNotDispatched(UsersUpdated::class);
});

it('hides the endpoint without the guilds feature, and for a missing guild', function (): void {
signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'missing'))->assertNotFound();

resolve(Features::class)->update(Feature::Guilds, false, adminOnly: false);

signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'rust'))->assertNotFound();
});

it('shares the 120 reads a minute with the web', function (): void {
foreach (range(1, 120) as $read) {
$this->actingAs($this->user)->put(route('guild-read.update', $this->guild->id))->assertRedirect();
}

signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'rust'))->assertTooManyRequests();
});

it('requires a signed request', function (): void {
$this->putJson(route('api-guild-read.update', 'rust'))->assertUnauthorized();
});
69 changes: 69 additions & 0 deletions tests/Feature/Controllers/Api/JoinedGuildControllerTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
<?php

declare(strict_types=1);

use App\Enums\Feature;
use App\Models\Commit;
use App\Models\Guild;
use App\Models\User;
use App\Services\Features;
use Illuminate\Support\Facades\DB;

beforeEach(function (): void {
resolve(Features::class)->update(Feature::Guilds, true, adminOnly: false);
$this->travelTo('2026-11-18 12:00:00');

$this->user = User::factory()->create();
$this->author = User::factory()->create();
$this->keyPair = apiKeyPairFor($this->user);
});

function joinApiGuild(User $user, Guild $guild, string $joinedAt, ?string $readAt = null, ?string $mutedAt = null): void
{
DB::table('guild_preferences')->insert(['user_id' => $user->id, 'guild_id' => $guild->id, 'joined_at' => $joinedAt, 'read_at' => $readAt, 'muted_at' => $mutedAt]);
}

it('lists the joined guilds as the left navigation on the web does, the most missed commits first', function (): void {
$quiet = Guild::factory()->create(['handle' => 'aardvark', 'name' => 'Aardvark', 'emoji' => '🐜']);
$busy = Guild::factory()->create(['handle' => 'rust', 'name' => 'Rust', 'emoji' => '🦀', 'icon_path' => 'guild-icons/rust.webp']);
joinApiGuild($this->user, $quiet, '2026-11-01 00:00:00');
joinApiGuild($this->user, $busy, '2026-11-01 00:00:00', '2026-11-18 10:00:00');
joinApiGuild($this->user, Guild::factory()->create(['handle' => 'muted']), '2026-11-01 00:00:00', mutedAt: '2026-11-02 00:00:00');
Guild::factory()->create(['handle' => 'unjoined']);

Commit::factory()->for($this->author)->create(['guild_id' => $busy->id, 'created_at' => '2026-11-18 09:00:00']);
Commit::factory()->for($this->author)->count(2)->create(['guild_id' => $busy->id, 'created_at' => '2026-11-18 11:00:00']);

signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index'))
->assertOk()
->assertJsonPath('data.*.handle', ['rust', 'aardvark'])
->assertJsonPath('data.0', [
'handle' => 'rust',
'name' => 'Rust',
'emoji' => '🦀',
'icon_url' => $busy->apiIconUrl($this->user),
'missed_commits' => 2,
'read_from' => '2026-11-18T10:00:00Z',
'html_url' => route('guild.show', 'rust'),
])
->assertJsonPath('data.1.missed_commits', 0)
->assertJsonPath('data.1.read_from', '2026-11-01T00:00:00Z');
});

it('lists nothing before the user joins a guild', function (): void {
Guild::factory()->create();

signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index'))
->assertOk()
->assertExactJson(['data' => []]);
});

it('hides the endpoint without the guilds feature', function (): void {
resolve(Features::class)->update(Feature::Guilds, false, adminOnly: false);

signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index'))->assertNotFound();
});

it('requires a signed request', function (): void {
$this->getJson(route('api-joined-guild.index'))->assertUnauthorized();
});