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

View file

@ -13,7 +13,7 @@
class="btn btn-primary w-fit" class="btn btn-primary w-fit"
commandfor="snapshot-picker" commandfor="snapshot-picker"
command="show-modal" 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-target="#snapshot-picker-body"
hx-swap="innerHTML" hx-swap="innerHTML"
hx-indicator="#snapshot-picker-scope" hx-indicator="#snapshot-picker-scope"
@ -34,7 +34,7 @@
<div> <div>
<h2 id="snapshot-title" class="picker-title">Select a snapshot</h2> <h2 id="snapshot-title" class="picker-title">Select a snapshot</h2>
<p id="snapshot-description" class="picker-description"> <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> </p>
</div> </div>
<button type="button" <button type="button"
@ -64,14 +64,14 @@
{% endif %} {% endif %}
<section class="grid gap-4 md:grid-cols-3"> <section class="grid gap-4 md:grid-cols-3">
<div class="p-4 card"> <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-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>
<div class="p-4 card"> <div class="p-4 card">
<p class="section-header-subtle">Default expiry</p> <p class="section-header-subtle">Default expiry</p>
<p class="mt-3 text-2xl font-semibold text-foreground">7 days</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>
<div class="p-4 card"> <div class="p-4 card">
<p class="section-header-subtle">Audit events</p> <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"> <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="text-sm font-semibold text-warning-foreground">Access token required</p>
<p class="mt-1 text-sm text-muted-foreground"> <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> </p>
<a href="/settings" class="btn btn-sm btn-primary mt-3 w-fit">Go to Settings</a> <a href="/settings" class="btn btn-sm btn-primary mt-3 w-fit">Go to Settings</a>
</div> </div>
@ -91,7 +91,7 @@
<div class="space-y-3"> <div class="space-y-3">
<div> <div>
<h2 class="text-base font-semibold">Share links</h2> <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> </div>
<section class="card"> <section class="card">
<div class="overflow-x-auto"> <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> <span class="mt-2 block">Draw a boundary around your code. Let them look, but don't let them scrape.</span>
</p> </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]"> <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. Sign in using Forgejo, register an access token, and control what can be viewed and by whom.
</p> </p>
<div class="mt-7 flex flex-wrap items-center justify-center gap-3"> <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> <h2 class="text-base font-semibold">Forgejo access token</h2>
<p class="mt-2 text-sm text-muted-foreground"> <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 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> </p>
{% if pat_registered %} {% if pat_registered %}
<div class="mt-4 card"> <div class="mt-4 card">

View file

@ -10,7 +10,7 @@
name="repo" name="repo"
required required
{% if not options %}disabled{% endif %} {% 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-trigger="change"
hx-target="#snapshot-branch-content" hx-target="#snapshot-branch-content"
hx-swap="innerHTML" hx-swap="innerHTML"
@ -36,7 +36,7 @@
name="ref" name="ref"
required required
{% if step != "branch" or not options %}disabled{% endif %} {% 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-trigger="change"
hx-include="#snapshot-repository" hx-include="#snapshot-repository"
hx-target="#snapshot-commit-content" hx-target="#snapshot-commit-content"
@ -57,7 +57,7 @@
{% if error %} {% if error %}
<button type="button" <button type="button"
class="btn btn-xs btn-secondary" 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-include="#snapshot-repository"
hx-target="#snapshot-branch-content" hx-target="#snapshot-branch-content"
hx-swap="innerHTML" hx-swap="innerHTML"
@ -79,7 +79,7 @@
<div> <div>
<label for="snapshot-commit" class="picker-step-label">Commit</label> <label for="snapshot-commit" class="picker-step-label">Commit</label>
{% if step == "commit" and repo and ref %} {% 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-target="#snapshot-picker-body"
hx-swap="innerHTML" hx-swap="innerHTML"
hx-indicator="#snapshot-picker-scope" hx-indicator="#snapshot-picker-scope"

View file

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