docs(web): clarify snapshot and share-link terminology

This commit is contained in:
ZTatman 2026-11-20 10:58:54 -05:00
parent d04219a36c
commit e4848c71ee
9 changed files with 32 additions and 21 deletions

View file

@ -76,7 +76,9 @@ Open `http://localhost:8000` in your browser. On first boot, Firebreak redirects
### 4. Sign In and Register Your Token
After setup, sign in with your Forgejo account via OAuth. On first login, Firebreak prompts you to register a `read:repository`-scoped Personal Access Token (PAT) to enable share link viewing.
After setup, sign in with your Forgejo account via OAuth. On first login, Firebreak prompts you to register a `read:repository`-scoped personal access token (PAT) so you can browse your repositories and preview snapshots.
See the [Firebreak glossary](docs/glossary.md) for the difference between snapshots, share links, and grants.
### 5. Alternative Deployments

11
docs/glossary.md Normal file
View file

@ -0,0 +1,11 @@
# Firebreak glossary
A **share link** opens a **snapshot**. A **grant** is the internal record Firebreak checks to decide whether to allow access.
| Term | Meaning | Where it belongs |
| --- | --- | --- |
| **Snapshot** | A repository's content at a specific commit SHA. The branch helps users find a commit; it does not change what a link opens later. | Picker, preview, and viewer copy. A snapshot doesn't need a separate database model. |
| **Share link** | The URL someone copies and sends to let others view a snapshot. | Dashboard copy, share-link API names, and `/links` routes for creating and managing links. |
| **Grant** | The stored access record: the repository and commit SHA, expiration, revocation, and any recipient restriction. | The `Grant` model, `grants` table, and backend authorization code. Use **share link**, not **grant**, in user-facing copy. |
The dashboard's snapshot picker lives under `/dashboard/snapshot-picker`. Selecting or clearing a preview does not create, publish, or revoke a share link. Existing JSON repository listings stay under `/links/repositories` for compatibility.

View file

@ -91,6 +91,7 @@ app.mount(
app.include_router(auth.router)
app.include_router(links.router)
app.include_router(repositories.router)
app.include_router(repositories.picker_router)
app.include_router(settings.router)
app.include_router(setup.router)

View file

@ -17,6 +17,7 @@ from app.settings import get_app_settings, get_fernet
from app.templating import templates
router = APIRouter(prefix="/links", tags=["repositories"])
picker_router = APIRouter(prefix="/dashboard/snapshot-picker", include_in_schema=False)
async def get_forgejo_token(
@ -131,9 +132,7 @@ RECENT_COMMITS = 30
PICKER_PAGE_SIZE = 50
@router.get(
"/snapshot-picker/preview", response_class=HTMLResponse, include_in_schema=False
)
@picker_router.get("/preview", response_class=HTMLResponse)
async def preview_snapshot(
request: Request,
_session: Annotated[UserBrowserSession, Depends(get_current_session)],
@ -152,9 +151,7 @@ async def preview_snapshot(
)
@router.get(
"/snapshot-picker/{step}", response_class=HTMLResponse, include_in_schema=False
)
@picker_router.get("/{step}", response_class=HTMLResponse)
async def get_snapshot_picker_step(
request: Request,
step: Literal["repository", "branch", "commit"],

View file

@ -13,7 +13,7 @@
class="btn btn-primary w-fit"
commandfor="snapshot-picker"
command="show-modal"
hx-get="/links/snapshot-picker/repository"
hx-get="{{ url_for('get_snapshot_picker_step', step='repository').path }}"
hx-target="#snapshot-picker-body"
hx-swap="innerHTML"
hx-indicator="#snapshot-picker-scope"
@ -34,7 +34,7 @@
<div>
<h2 id="snapshot-title" class="picker-title">Select a snapshot</h2>
<p id="snapshot-description" class="picker-description">
Choose a repository, then a branch and commit. Nothing is published until you create a link.
Choose a repository, then a branch and commit. This previews a snapshot without creating a share link.
</p>
</div>
<button type="button"
@ -64,14 +64,14 @@
{% endif %}
<section class="grid gap-4 md:grid-cols-3">
<div class="p-4 card">
<p class="section-header-subtle">Active links</p>
<p class="section-header-subtle">Active share links</p>
<p class="mt-3 text-2xl font-semibold text-foreground">0</p>
<p class="mt-2 text-xs text-muted-foreground">No repository snapshots published yet.</p>
<p class="mt-2 text-xs text-muted-foreground">No active share links yet.</p>
</div>
<div class="p-4 card">
<p class="section-header-subtle">Default expiry</p>
<p class="mt-3 text-2xl font-semibold text-foreground">7 days</p>
<p class="mt-2 text-xs text-muted-foreground">Applied to newly created links.</p>
<p class="mt-2 text-xs text-muted-foreground">Applied to newly created share links.</p>
</div>
<div class="p-4 card">
<p class="section-header-subtle">Audit events</p>
@ -83,7 +83,7 @@
<div class="rounded-lg border border-warning-muted bg-warning-muted/40 px-5 py-4">
<p class="text-sm font-semibold text-warning-foreground">Access token required</p>
<p class="mt-1 text-sm text-muted-foreground">
Register a Forgejo access token to create share links.
Register a Forgejo access token to browse repositories and select a snapshot.
</p>
<a href="/settings" class="btn btn-sm btn-primary mt-3 w-fit">Go to Settings</a>
</div>
@ -91,7 +91,7 @@
<div class="space-y-3">
<div>
<h2 class="text-base font-semibold">Share links</h2>
<p class="mt-2 text-sm text-muted-foreground">Repository snapshots published from this account.</p>
<p class="mt-2 text-sm text-muted-foreground">Share links you’ve created.</p>
</div>
<section class="card">
<div class="overflow-x-auto">

View file

@ -28,7 +28,7 @@
<span class="mt-2 block">Draw a boundary around your code. Let them look, but don't let them scrape.</span>
</p>
<p class="mt-7 max-w-xl rounded-lg border border-[#f7f2e8]/14 bg-[#17191c]/42 px-5 py-4 text-sm leading-6 text-[#f7f2e8]/76 shadow-[0_18px_50px_rgb(0_0_0_/0.24)] backdrop-blur-sm sm:text-[0.9375rem]">
Firebreak creates temporary, read-only links to private Forgejo repository snapshots.
Firebreak is designed for sharing read-only snapshots of private Forgejo repositories through temporary share links.
Sign in using Forgejo, register an access token, and control what can be viewed and by whom.
</p>
<div class="mt-7 flex flex-wrap items-center justify-center gap-3">

View file

@ -14,7 +14,7 @@
<h2 class="text-base font-semibold">Forgejo access token</h2>
<p class="mt-2 text-sm text-muted-foreground">
A <code class="rounded-sm bg-secondary px-1.5 py-0.5 text-foreground">read:repository</code>-scoped
Personal Access Token is required for share link viewing.
personal access token lets Firebreak browse your repositories and preview snapshots.
</p>
{% if pat_registered %}
<div class="mt-4 card">

View file

@ -10,7 +10,7 @@
name="repo"
required
{% if not options %}disabled{% endif %}
hx-get="/links/snapshot-picker/branch"
hx-get="{{ url_for('get_snapshot_picker_step', step='branch').path }}"
hx-trigger="change"
hx-target="#snapshot-branch-content"
hx-swap="innerHTML"
@ -36,7 +36,7 @@
name="ref"
required
{% if step != "branch" or not options %}disabled{% endif %}
hx-get="/links/snapshot-picker/commit"
hx-get="{{ url_for('get_snapshot_picker_step', step='commit').path }}"
hx-trigger="change"
hx-include="#snapshot-repository"
hx-target="#snapshot-commit-content"
@ -57,7 +57,7 @@
{% if error %}
<button type="button"
class="btn btn-xs btn-secondary"
hx-get="/links/snapshot-picker/branch"
hx-get="{{ url_for('get_snapshot_picker_step', step='branch').path }}"
hx-include="#snapshot-repository"
hx-target="#snapshot-branch-content"
hx-swap="innerHTML"
@ -79,7 +79,7 @@
<div>
<label for="snapshot-commit" class="picker-step-label">Commit</label>
{% if step == "commit" and repo and ref %}
<form hx-get="/links/snapshot-picker/preview"
<form hx-get="{{ url_for('preview_snapshot').path }}"
hx-target="#snapshot-picker-body"
hx-swap="innerHTML"
hx-indicator="#snapshot-picker-scope"

View file

@ -12,7 +12,7 @@
</div>
<button type="button"
class="btn btn-xs btn-secondary"
hx-get="/links/snapshot-picker/preview"
hx-get="{{ url_for('preview_snapshot').path }}"
hx-target="#selected-snapshot"
hx-swap="outerHTML">Clear</button>
</div>