Commit 911804f719
Verified · cmc
Layout: unified · split
API.md +4 −5
| @@ -44,8 +44,8 @@ Contribution ranges: | |||
| 44 | 44 | ||
| 45 | - Contribution read endpoints return zero-filled days, so clients do not need to patch missing dates. | 45 | - Contribution read endpoints return zero-filled days, so clients do not need to patch missing dates. |
| 46 | - Public contribution reads also register the actor for background indexing. A first lookup may therefore return an empty graph while the scheduler catches up. | 46 | - Public contribution reads also register the actor for background indexing. A first lookup may therefore return an empty graph while the scheduler catches up. |
| 47 | - Incremental indexing and historical backfill are separate. An actor can be recently indexed without being fully backfilled yet. | 47 | - Incremental indexing and one-year backfill are separate. An actor can be recently indexed before the retained one-year window is fully filled in. |
| 48 | - The service prioritizes a recent visible history window first, then continues deep-history backfill afterward. | 48 | - The service only retains and backfills the most recent 365 days of activity. |
| 49 | 49 | ||
| 50 | Background polling: | 50 | Background polling: |
| 51 | 51 | ||
| @@ -112,8 +112,7 @@ Behavior notes: | |||
| 112 | - This endpoint resolves aliases to a canonical actor before querying data. | 112 | - This endpoint resolves aliases to a canonical actor before querying data. |
| 113 | - This endpoint also registers the actor for background indexing and updates the actor's `last_requested_at` timestamp. | 113 | - This endpoint also registers the actor for background indexing and updates the actor's `last_requested_at` timestamp. |
| 114 | - The response is always immediate; it does not wait for SourceHut polling to finish. | 114 | - The response is always immediate; it does not wait for SourceHut polling to finish. |
| 115 | - Historical backfill runs in bounded background batches and may take multiple scheduler passes to complete. | 115 | - One-year backfill runs in bounded background batches and may take multiple scheduler passes to complete. |
| 116 | - The recent visible window is prioritized before full-history backfill so clients can show a useful graph sooner. | ||
| 117 | 116 | ||
| 118 | Example by year: | 117 | Example by year: |
| 119 | 118 | ||
| @@ -305,7 +304,7 @@ Response fields: | |||
| 305 | Behavior notes: | 304 | Behavior notes: |
| 306 | 305 | ||
| 307 | - Manual polling also updates the actor's indexing metadata. | 306 | - Manual polling also updates the actor's indexing metadata. |
| 308 | - Manual polling also advances historical backfill by one bounded batch per supported service. | 307 | - Manual polling also advances one-year backfill by bounded batches for each supported service. |
| 309 | - Git polling auto-discovers the actor's owned repositories and unions in any configured tracked repositories. | 308 | - Git polling auto-discovers the actor's owned repositories and unions in any configured tracked repositories. |
| 310 | 309 | ||
| 311 | Possible errors: | 310 | Possible errors: |
README.md +2 −2
| @@ -14,7 +14,7 @@ The current V1 is intentionally narrow and production-oriented: | |||
| 14 | 14 | ||
| 15 | ## What It Does | 15 | ## What It Does |
| 16 | 16 | ||
| 17 | The service collects SourceHut activity from one or more sr.ht GraphQL services, turns those records into a canonical event shape, aggregates activity by day, and returns zero-filled calendar ranges so the client never has to patch missing dates. It performs recent incremental polling, prioritizes a recent visible-history window for faster UX, and then continues bounded historical backfill. | 17 | The service collects SourceHut activity from one or more sr.ht GraphQL services, turns those records into a canonical event shape, aggregates activity by day, and returns zero-filled calendar ranges so the client never has to patch missing dates. It performs recent incremental polling, backfills the most recent 365 days for newly requested actors, and prunes older activity from storage. |
| 18 | 18 | ||
| 19 | Example use cases: | 19 | Example use cases: |
| 20 | 20 | ||
| @@ -165,7 +165,7 @@ Example response: | |||
| 165 | } | 165 | } |
| 166 | ``` | 166 | ``` |
| 167 | 167 | ||
| 168 | Scheduled polling only runs when `ENABLE_SCHEDULER=true`. The scheduler seeds `DEFAULT_ACTOR` as an initial known actor, runs one poll immediately at startup, and public contribution reads register additional actors for later background polling and historical backfill. | 168 | Scheduled polling only runs when `ENABLE_SCHEDULER=true`. The scheduler seeds `DEFAULT_ACTOR` as an initial known actor, runs one poll immediately at startup, and public contribution reads register additional actors for later background polling and one-year backfill. |
| 169 | 169 | ||
| 170 | For `git.sr.ht`, owned repositories are auto-discovered for the actor. `GIT_TRACKED_REPOSITORIES` can still be used to union in extra repositories. Entries may be either: | 170 | For `git.sr.ht`, owned repositories are auto-discovered for the actor. `GIT_TRACKED_REPOSITORIES` can still be used to union in extra repositories. Entries may be either: |
| 171 | 171 | ||