Skip to content
Merged
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
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- `hn front --feed` reads the `top`, `new`, `best`, `ask`, `show` and `job` lists.
- `hn read` flags `-n`, `--replies`, `--depth` and `--max-chars`, and comment IDs
in its output. `hn read COMMENT_ID` opens a collapsed thread.

### Changed
- `hn read` caps its output by default, and says what it leaves out. `--expand`
shows everything.

### Fixed
- `hn front` lists stories in site rank order. Algolia's `front_page` tag has
the right stories in another order.
- `hn read` lists comments in site rank order, not oldest first.

## [0.3.0] — 2026-11-05

### Added
Expand Down
25 changes: 17 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,8 @@ $ hn front -n 3
3. [145pts 53c] The death of microservices @mfiguiere 6h ago
https://example.com/microservices

$ hn read 43163011 --json | jq '.comments | length'
963
$ hn read 43163011 --json | jq '.children | length'
412
```

Run `hn --help` for the full command tree.
Expand Down Expand Up @@ -100,13 +100,22 @@ hn search "github.com/voska" --url
# Next page of results
hn search "WASM" --page 1

# Current front page
# Current front page, in site rank order
hn front

# Read a story with comments (3 levels deep)
# Other feeds: new, best, ask, show, job
hn front --feed show -n 10

# Read a story with its top comments
hn read 43163011

# Read with all comments expanded
# Open a collapsed thread by comment ID
hn read 43163150

# Fewer comments, shorter
hn read 43163011 -n 5 --replies 1 --max-chars 300

# Read every comment in full
hn read 43163011 --expand

# User profile
Expand All @@ -126,7 +135,7 @@ npx skills add -g voska/hn-cli

## API

Uses the [HN Algolia API](https://hn.algolia.com/api/v1/) for search and threads, and the [official Firebase API](https://github.com/HackerNews/API) for user profiles. Both are free and public, with no authentication or API keys required.
Uses the [HN Algolia API](https://hn.algolia.com/api/v1/) for search and threads, and the [official Firebase API](https://github.com/HackerNews/API) for site ranking and user profiles. Both are free and public, with no authentication or API keys required.

## Output Modes

Expand All @@ -140,8 +149,8 @@ Uses the [HN Algolia API](https://hn.algolia.com/api/v1/) for search and threads
| Command | Alias | Description |
|---------|-------|-------------|
| `search [query]` | `s` | Search stories or comments |
| `front` | `f` | Current front page stories |
| `read <id>` | `r` | Story with threaded comments |
| `front` | `f` | Stories in site rank order, from any feed |
| `read <id>` | `r` | Story or comment with its top comments |
| `user <username>` | `u` | User profile and karma |
| `status` | | API health check with latency |
| `version` | | Version, commit, build date |
Expand Down
217 changes: 217 additions & 0 deletions internal/api/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,10 @@ import (
"net/http"
"net/url"
"regexp"
"sort"
"strconv"
"strings"
"sync"
"time"
)

Expand All @@ -20,6 +22,23 @@ const (
FirebaseURL = "https://hacker-news.firebaseio.com/v0"
)

const (
// feedChunk is how many story IDs fit in one Algolia tag filter.
feedChunk = 100
// maxConcurrent caps parallel Firebase requests.
maxConcurrent = 10
)

// feedLists maps feed names to Firebase story lists.
var feedLists = map[string]string{
"top": "topstories",
"new": "newstories",
"best": "beststories",
"ask": "askstories",
"show": "showstories",
"job": "jobstories",
}

var (
// ErrNotFound means the requested item or user does not exist.
ErrNotFound = errors.New("not found")
Expand Down Expand Up @@ -120,6 +139,33 @@ type User struct {
Karma int `json:"karma"`
}

// firebaseItem is an item from the Firebase API.
type firebaseItem struct {
ID int `json:"id"`
By string `json:"by"`
Title string `json:"title"`
URL string `json:"url"`
Score int `json:"score"`
Descendants int `json:"descendants"`
Time int64 `json:"time"`
Dead bool `json:"dead"`
Deleted bool `json:"deleted"`
Kids []int `json:"kids"`
}

func (f firebaseItem) hit() Hit {
return Hit{
ObjectID: strconv.Itoa(f.ID),
Title: f.Title,
URL: f.URL,
Author: f.By,
Points: f.Score,
NumComments: f.Descendants,
CreatedAt: time.Unix(f.Time, 0).UTC().Format(time.RFC3339),
CreatedAtI: f.Time,
}
}

// SearchOptions configures a search request.
type SearchOptions struct {
Query string
Expand Down Expand Up @@ -184,6 +230,177 @@ func (c *Client) Search(opts SearchOptions) (*SearchResult, error) {
return &result, nil
}

// FeedNames returns the valid feed names, sorted.
func FeedNames() []string {
names := make([]string, 0, len(feedLists))
for name := range feedLists {
names = append(names, name)
}
sort.Strings(names)
return names
}

// Feed returns the first n stories of a feed in site rank order. The order
// comes from Firebase and the details from Algolia, with single Firebase
// lookups for what Algolia lacks: job posts and stories not indexed yet.
func (c *Client) Feed(feed string, n int) (*SearchResult, error) {
list, ok := feedLists[feed]
if !ok {
return nil, fmt.Errorf("unknown feed %q (use %s)", feed, strings.Join(FeedNames(), ", "))
}

var ids []int
if err := c.getJSON(fmt.Sprintf("%s/%s.json", c.firebaseURL, list), &ids); err != nil {
return nil, fmt.Errorf("feed %s: %w", feed, err)
}
if n > 0 && n < len(ids) {
ids = ids[:n]
}

found := make(map[string]Hit, len(ids))
for start := 0; start < len(ids); start += feedChunk {
chunk := ids[start:min(start+feedChunk, len(ids))]
tags := make([]string, len(chunk))
for i, id := range chunk {
tags[i] = fmt.Sprintf("story_%d", id)
}
result, err := c.Search(SearchOptions{
Tags: "(story,job),(" + strings.Join(tags, ",") + ")",
NumResults: len(chunk),
})
if err != nil {
return nil, err
}
for _, hit := range result.Hits {
found[hit.ObjectID] = hit
}
}

if err := c.fillMissing(ids, found); err != nil {
return nil, err
}

hits := make([]Hit, 0, len(ids))
for _, id := range ids {
if hit, ok := found[strconv.Itoa(id)]; ok {
hits = append(hits, hit)
}
}
return &SearchResult{Hits: hits, NbHits: len(hits), HitsPerPage: len(ids)}, nil
}

// fillMissing adds to found the ids it lacks, looked up on Firebase. Dead and
// deleted items stay out.
func (c *Client) fillMissing(ids []int, found map[string]Hit) error {
var missing []int
for _, id := range ids {
if _, ok := found[strconv.Itoa(id)]; !ok {
missing = append(missing, id)
}
}

var (
wg sync.WaitGroup
mu sync.Mutex
firstErr error
slots = make(chan struct{}, maxConcurrent)
)
for _, id := range missing {
wg.Add(1)
slots <- struct{}{}
go func() {
defer wg.Done()
defer func() { <-slots }()

fb, err := c.firebaseItem(id)
mu.Lock()
defer mu.Unlock()
switch {
case err != nil:
if firstErr == nil {
firstErr = err
}
case fb != nil && !fb.Dead && !fb.Deleted:
found[strconv.Itoa(id)] = fb.hit()
}
}()
}
wg.Wait()
return firstErr
}

// firebaseItem fetches one item from the Firebase API. It returns nil when the
// item does not exist.
func (c *Client) firebaseItem(id int) (*firebaseItem, error) {
var fb *firebaseItem
if err := c.getJSON(fmt.Sprintf("%s/item/%d.json", c.firebaseURL, id), &fb); err != nil {
return nil, fmt.Errorf("item %d: %w", id, err)
}
return fb, nil
}

// RankComments sorts item's comments into site rank order, and the replies of
// the first n comments too. Algolia returns comments oldest first, and only
// Firebase knows the ranking. Deeper replies stay oldest first.
func (c *Client) RankComments(item *Item, n int) error {
if err := c.rankChildren(item); err != nil {
return err
}

children := item.Children
if n <= 0 {
return nil
}
if n < len(children) {
children = children[:n]
}

var (
wg sync.WaitGroup
slots = make(chan struct{}, maxConcurrent)
)
for i := range children {
if len(children[i].Children) < 2 {
continue
}
wg.Add(1)
slots <- struct{}{}
go func() {
defer wg.Done()
defer func() { <-slots }()
// Replies are only reordered, so a failed lookup costs nothing.
_ = c.rankChildren(&children[i])
}()
}
wg.Wait()
return nil
}

func (c *Client) rankChildren(item *Item) error {
fb, err := c.firebaseItem(item.ID)
if err != nil {
return err
}
if fb == nil {
return fmt.Errorf("item %d: %w", item.ID, ErrNotFound)
}

rank := make(map[int]int, len(fb.Kids))
for i, id := range fb.Kids {
rank[id] = i
}
position := func(id int) int {
if r, ok := rank[id]; ok {
return r
}
return len(fb.Kids)
}
sort.SliceStable(item.Children, func(i, j int) bool {
return position(item.Children[i].ID) < position(item.Children[j].ID)
})
return nil
}

// GetItem fetches a single item (story/comment) with its children.
func (c *Client) GetItem(id string) (*Item, error) {
var item Item
Expand Down
Loading
Loading