Star history for tangled repositories
tangled-stars.com
atproto
git
tangled
Add Constellation resolution, backfill, star history
juprodh.me
(Jul 11, 2026, 10:11 PM +0800)
ec137a3b
69183ad6
+849
-3
+2
-1
backend/deno.json
+2
-1
backend/deno.json
+21
-2
backend/main.ts
+21
-2
backend/main.ts
···
1
1
// Backend entrypoint: Hono API served on Deno.serve.
2
-
// Foundation only — /healthz plus opening the SQLite store on boot. The star
3
-
// data routes (/api/repo, /api/trending) and /svg render land in later commits.
2
+
// /healthz + /api/repo (star history from the local store). /api/trending and
3
+
// the /svg render land in later commits.
4
4
import { Hono } from "hono"
5
5
import { cors } from "hono/cors"
6
+
import type { ContentfulStatusCode } from "hono/utils/http-status"
6
7
import logger from "./logger.ts"
7
8
import "./db.ts" // opens the SQLite store + runs migrations on boot
9
+
import { getRepoFromDb } from "./stars.ts"
10
+
import { normalizeRepoInput } from "../shared/common/api.ts"
8
11
9
12
const app = new Hono()
10
13
···
23
26
})
24
27
25
28
app.get("/healthz", (c) => c.json({ status: "OK", commit: Deno.env.get("GIT_COMMIT") || "unknown" }))
29
+
30
+
// JSON star data for the frontend, served from the local SQLite store
31
+
// (Jetstream-fed + Constellation-backfilled): { repo, starRecords, count, logoUrl }.
32
+
app.get("/api/repo", async (c) => {
33
+
const repo = c.req.query("repo")
34
+
if (!repo) return c.json({ error: "repo query param required" }, 400)
35
+
try {
36
+
const data = await getRepoFromDb(normalizeRepoInput(repo.trim()))
37
+
return c.json(data)
38
+
} catch (err) {
39
+
const e = err as { status?: number; data?: string; message?: string }
40
+
const message = (typeof e.data === "string" ? e.data : e.message) || "Failed to fetch repo"
41
+
logger.error(`/api/repo ${repo}: ${message}`)
42
+
return c.json({ error: message }, (e.status ?? 500) as ContentfulStatusCode)
43
+
}
44
+
})
26
45
27
46
const port = Number(Deno.env.get("PORT")) || 8080
28
47
Deno.serve(
+163
backend/stars.ts
+163
backend/stars.ts
···
1
+
// Serve a repo's star history from the local SQLite store. On the first request
2
+
// for a repo we backfill its full history from Constellation (both star formats);
3
+
// thereafter the Jetstream ingester keeps it fresh, so reads are a single query.
4
+
import api, { decodeTidTimestamp, fetchBacklinkRecords, resolveRepo, STAR_COLLECTION } from "../shared/common/api.ts"
5
+
import type { RepoRef } from "../shared/common/api.ts"
6
+
import utils from "../shared/common/utils.ts"
7
+
import {
8
+
addStars,
9
+
getRepo,
10
+
getRepoLogo,
11
+
getResolution,
12
+
getStarTimestamps,
13
+
markBackfilled,
14
+
setRepoLogo,
15
+
setResolution,
16
+
upsertRepo,
17
+
} from "./db.ts"
18
+
import type { StarInput } from "./db.ts"
19
+
import logger from "./logger.ts"
20
+
21
+
export interface RepoStarData {
22
+
repo: string
23
+
starRecords: { date: string; count: number }[]
24
+
count: number
25
+
logoUrl: string
26
+
}
27
+
28
+
// Disk-cached resolution; TTL bounds staleness from handle re-mappings / repo deletes.
29
+
const RESOLUTION_TTL_MS = Number(Deno.env.get("RESOLUTION_TTL_HOURS") || 24) * 3600 * 1000
30
+
31
+
// "owner/repo" → canonical key + resolved at-uri/repoDid, persisted for bookkeeping.
32
+
async function resolve(repo: string): Promise<{ repoKey: string; ref: RepoRef }> {
33
+
const inputKey = repo.toLowerCase()
34
+
const name = repo.slice(repo.indexOf("/") + 1)
35
+
36
+
let ref: RepoRef
37
+
const cached = getResolution(inputKey)
38
+
if (cached && Date.now() - cached.resolvedAtMs < RESOLUTION_TTL_MS) {
39
+
ref = { atUri: cached.atUri, atUris: cached.atUris, repoDid: cached.repoDid }
40
+
} else {
41
+
ref = await resolveRepo(repo) // throws { status: 404 } if the repo doesn't exist
42
+
setResolution(inputKey, ref.atUri, ref.atUris, ref.repoDid)
43
+
}
44
+
45
+
const ownerDid = ref.atUri.split("/")[2]
46
+
const repoKey = `${ownerDid}/${name.toLowerCase()}`
47
+
// Idempotent upsert on both paths ensures the repos row exists even after a mid-write crash.
48
+
upsertRepo({
49
+
repo_key: repoKey,
50
+
owner_did: ownerDid,
51
+
repo_did: ref.repoDid || null,
52
+
at_uri: ref.atUri,
53
+
name,
54
+
})
55
+
return { repoKey, ref }
56
+
}
57
+
58
+
// One-time Constellation sweep, de-duplicated against concurrent requests.
59
+
const backfillInFlight = new Map<string, Promise<void>>()
60
+
61
+
export function ensureBackfilled(repoKey: string, ref: RepoRef): Promise<void> {
62
+
const existing = getRepo(repoKey)
63
+
if (existing?.backfilled_at) return Promise.resolve()
64
+
65
+
const inFlight = backfillInFlight.get(repoKey)
66
+
if (inFlight) return inFlight
67
+
68
+
const p = doBackfill(repoKey, ref).finally(() => backfillInFlight.delete(repoKey))
69
+
backfillInFlight.set(repoKey, p)
70
+
return p
71
+
}
72
+
73
+
async function doBackfill(repoKey: string, ref: RepoRef): Promise<void> {
74
+
// Old-format stars across every at-uri the repo has + new-format stars by repoDid.
75
+
// The scattered old-format stars are why tangled.org/core reads ~1150, not ~217.
76
+
const oldByUri = await Promise.all(
77
+
ref.atUris.map((uri) =>
78
+
fetchBacklinkRecords(uri, `${STAR_COLLECTION}:subject`).then((recs) => ({ uri, recs }))
79
+
),
80
+
)
81
+
const newRecs = ref.repoDid ? await fetchBacklinkRecords(ref.repoDid, `${STAR_COLLECTION}:subject.did`) : []
82
+
83
+
const rows: StarInput[] = []
84
+
let oldCount = 0
85
+
for (const { uri, recs } of oldByUri) {
86
+
for (const r of recs) {
87
+
rows.push({
88
+
stargazerDid: r.did,
89
+
rkey: r.rkey,
90
+
// Normalize to repoDid so scattered old-format stars key off one id; subject_uri
91
+
// stays for repos without a repoDid.
92
+
subjectDid: ref.repoDid || null,
93
+
subjectUri: uri,
94
+
createdAt: new Date(decodeTidTimestamp(r.rkey)).toISOString(),
95
+
})
96
+
oldCount++
97
+
}
98
+
}
99
+
for (const r of newRecs) {
100
+
rows.push({
101
+
stargazerDid: r.did,
102
+
rkey: r.rkey,
103
+
subjectDid: ref.repoDid,
104
+
subjectUri: null,
105
+
createdAt: new Date(decodeTidTimestamp(r.rkey)).toISOString(),
106
+
})
107
+
}
108
+
109
+
addStars(rows)
110
+
markBackfilled(repoKey)
111
+
const nRec = ref.atUris.length
112
+
logger.info(
113
+
`[backfill] ${repoKey}: ${oldCount} old-format (${nRec} record${
114
+
nRec === 1 ? "" : "s"
115
+
}) + ${newRecs.length} new-format stars`,
116
+
)
117
+
}
118
+
119
+
// Cumulative star curve: one point per star + a final "today" endpoint. Same
120
+
// { date, count }[] shape as the direct Constellation path in api.tsx.
121
+
function buildStarRecords(timestampsMs: number[]): { date: string; count: number }[] {
122
+
if (timestampsMs.length === 0) return []
123
+
const sorted = timestampsMs.slice().sort((a, b) => a - b)
124
+
const map = new Map<string, number>()
125
+
let running = 0
126
+
for (const ms of sorted) {
127
+
running++
128
+
map.set(utils.getDateString(ms), running)
129
+
}
130
+
map.set(utils.getDateString(Date.now()), sorted.length)
131
+
132
+
const records: { date: string; count: number }[] = []
133
+
map.forEach((count, date) => records.push({ date, count }))
134
+
return records
135
+
}
136
+
137
+
// Everything the frontend needs for one repo, served from the DB.
138
+
export async function getRepoFromDb(repo: string): Promise<RepoStarData> {
139
+
const { repoKey, ref } = await resolve(repo)
140
+
141
+
// Avatar is cached in the DB after the first fetch (null = never fetched).
142
+
let logoUrl = getRepoLogo(repoKey)
143
+
const [, fetchedLogo] = await Promise.all([
144
+
ensureBackfilled(repoKey, ref),
145
+
logoUrl === null ? api.getRepoLogoUrl(repo).catch(() => "") : Promise.resolve(logoUrl),
146
+
])
147
+
if (logoUrl === null) {
148
+
logoUrl = fetchedLogo
149
+
setRepoLogo(repoKey, logoUrl)
150
+
}
151
+
152
+
const timestamps = getStarTimestamps(ref.repoDid || null, ref.atUris)
153
+
// A repo that exists but has no stars yet still needs a renderable point.
154
+
const starRecords = timestamps.length
155
+
? buildStarRecords(timestamps)
156
+
: [{ date: utils.getDateString(Date.now(), "yyyy/MM/dd"), count: 0 }]
157
+
return {
158
+
repo,
159
+
starRecords,
160
+
count: timestamps.length,
161
+
logoUrl,
162
+
}
163
+
}