oxidecomputer / oxidecomputer/dropshot

server lifecycle docs are sparse, wrong

Open
#323 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
1.2k
Forks
104
Avg merge
1d 19h
Merged PRs (30d)
22

Description

In the latest release, the docs for HttpServerStarter say:

You must invoke start() on the returned instance of HttpServerStarter (and await the result) to actually start the server.

I'm not sure if that was true in 0.6.0, but I don't think it's true today. start() appears to spawn one or more tasks that run the server. (I'm not sure if this is the task spawned by the wrapped start() methods or one started by hyper, but empirically, it does appear to be true.) You don't have to await on the server itself unless you want to wait for the server to stop.

That comment is still in "main":
https://github.com/oxidecomputer/dropshot/blob/main/dropshot/src/server.rs#L229-L236

But that's now on a private function on a private type. In "main", the public HttpServerStarter::new and HttpServerStarter::start have no docs:
https://github.com/oxidecomputer/dropshot/blob/main/dropshot/src/server.rs#L98
https://github.com/oxidecomputer/dropshot/blob/main/dropshot/src/server.rs#L154

Even in the released version, this whole process seems underdocumented.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read dropshot/src/server.rs at the public HttpServerStarter::new and start methods (around lines 98 and 154), then compare them with the stale private documentation around lines 229-236. Clarify the lifecycle, including when start() runs the server and what awaiting the server does, and document the complete process for users.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
backend, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.