You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* docs: rewrite README, docs, and CLI --help for clarity
tighten prose across README, environment-variables.md, metrics.md, and
tracing.md; straighten the CLI help text and fix a few factual slips.
- main.go: add short Usage on top-level, `start`, and `ask` commands;
rewrite flag descriptions in active voice; swap Usage/UsageText to
ArgsUsage on ask subcommands so `--help` renders the name, description,
and args correctly
- main.go: guard the hardcoded libp2p-listen-addrs default with a note
pointing at libp2p.DefaultListenAddrs + libp2p.DefaultTransports so
future go-libp2p bumps trigger a re-diff
- README.md: active voice, drop press-release filler, correct the public-
utility attribution to Shipyard, fix the redundant release step
- docs/environment-variables.md: drop "whether or not" double negatives,
active voice throughout, replace the self-referential default for
SOMEGUY_LIBP2P_LISTEN_ADDRS with a pointer to `someguy start --help`
so docs cannot drift from the CLI default
- docs/metrics.md: fix "Prometheus Glient" typo, plural/subject-verb
agreement, and document the previously-missing
someguy_cached_addr_book_probed_peers counter
- docs/tracing.md: fix the example port (8090 -> 8190, matching
SOMEGUY_LISTEN_ADDRESS default), drop broken headers.md links, and
clarify that tracing covers inbound HTTP routing requests (someguy is
a routing server, not a gateway)
* chore: release v0.12.0
- Docker image builder bumped to `golang:1.26-bookworm`
25
-
26
-
### Removed
35
+
- clearer `--help` descriptions for `someguy`, `someguy start`, and `someguy ask` (including per-subcommand short descriptions and correct `USAGE` lines)
36
+
- README, `docs/environment-variables.md`, `docs/metrics.md`, and `docs/tracing.md` rewritten for clarity (active voice, removed duplicated wording)
27
37
28
38
### Fixed
29
39
30
-
### Security
40
+
-`docs/environment-variables.md`: replaced the self-referential default for `SOMEGUY_LIBP2P_LISTEN_ADDRS` with a pointer to `someguy start --help` so the docs cannot drift from the CLI default
41
+
-`docs/metrics.md`: fixed "Prometheus Glient" typo, corrected plural/subject-verb agreement, and documented the previously-undocumented `someguy_cached_addr_book_probed_peers` counter
42
+
-`docs/tracing.md`: corrected the example port (`8090` → `8190`, matching `SOMEGUY_LISTEN_ADDRESS` default), replaced broken `headers.md` links with inline descriptions, and clarified that tracing covers inbound HTTP routing requests (not "gateway" requests)
Copy file name to clipboardExpand all lines: README.md
+12-12Lines changed: 12 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@
10
10
11
11
Someguy is an [HTTP Delegated Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) server that proxies requests to the [Amino DHT](https://docs.ipfs.tech/concepts/glossary/#amino) and other Delegated Routing servers such as the [Network Indexer](https://cid.contact).
12
12
13
-
Someguy is also hosted as a [public utility](https://docs.ipfs.tech/concepts/public-utilities/#delegated-routing-endpoint) at `https://delegated-ipfs.dev/routing/v1`.
13
+
[Shipyard](https://ipshipyard.com/)also runs a [public Someguy instance](https://docs.ipfs.tech/concepts/public-utilities/#delegated-routing-endpoint) at `https://delegated-ipfs.dev/routing/v1`.
14
14
15
15
## Build
16
16
@@ -39,7 +39,7 @@ Automated Docker container releases are available from the [Github container reg
39
39
-`staging-YYYY-DD-MM-GITSHA` points at a specific commit from the `staging` branch
40
40
- This tag is used by developers for internal testing, not intended for end users
41
41
42
-
When using Docker, make sure to pass necessary config via `-e`:
42
+
When using Docker, pass configuration via `-e`:
43
43
```console
44
44
$ docker pull ghcr.io/ipfs/someguy:main-latest
45
45
$ docker run --rm -it --net=host ghcr.io/ipfs/someguy:main-latest
@@ -49,23 +49,23 @@ See [`/docs/environment-variables.md`](./docs/environment-variables.md).
49
49
50
50
## Usage
51
51
52
-
You can use `someguy` as a client, or as a server.
52
+
Run `someguy` as a client or as a server.
53
53
54
54
### Server
55
55
56
-
You can start the server with `someguy start`. This will, by default, run a Delegated Routing V1 server that proxies requests to the [IPFS Amino DHT](https://blog.ipfs.tech/2023-09-amino-refactoring/) and the [cid.contact](https://cid.contact) indexer (IPNI) node.
56
+
Start the server with `someguy start`. By default it proxies requests to the [IPFS Amino DHT](https://blog.ipfs.tech/2023-09-amino-refactoring/) and the [cid.contact](https://cid.contact) indexer (IPNI) node.
57
57
58
-
For more details run `someguy start --help`.
58
+
For more details, run `someguy start --help`.
59
59
60
60
### Client
61
61
62
-
If you don't want to run a server yourself, but want to query some other server, you can run `someguy ask` and choose any of the subcommands and ask for a provider, a peer, or even an IPNS record.
62
+
To query an existing server without running one yourself, use `someguy ask <subcommand>` to look up a provider, peer, or IPNS record.
63
63
64
-
For more details run `someguy ask --help`.
64
+
For more details, run `someguy ask --help`.
65
65
66
66
### AutoConf
67
67
68
-
Automatic configuration of bootstrap peers and delegated routing endpoints. When enabled (default), the `auto` placeholder is replaced with network-recommended values fetched from a remote URL.
68
+
Automatic configuration of bootstrap peers and delegated routing endpoints. When enabled (default), Someguy replaces the `auto` placeholder with network-recommended values fetched from a remote URL.
Whether or not the Cached Address Book is enabled or not. If disabled, someguy will not return cached addresses for peers without multiaddrs in `FindProviders`.
50
+
Enables the cached address book. When disabled, Someguy omits cached addresses from `FindProviders` results for peers lacking multiaddrs.
51
51
52
52
Default: `true`
53
53
54
54
### `SOMEGUY_CACHED_ADDR_BOOK_RECENT_TTL`
55
55
56
-
The TTL for recently connected peers' multiaddrs in the cached address book. Only applies if`SOMEGUY_CACHED_ADDR_BOOK` is enabled.
56
+
TTL for recently connected peers' multiaddrs in the cached address book. Applies only when`SOMEGUY_CACHED_ADDR_BOOK` is enabled.
57
57
58
58
Default: `48h`
59
59
60
60
### `SOMEGUY_CACHED_ADDR_BOOK_ACTIVE_PROBING`
61
61
62
-
Whether or not the Cached Address Book should actively probe peers in cache to keep their multiaddrs up to date. Only applies if`SOMEGUY_CACHED_ADDR_BOOK` is enabled.
62
+
Enables active probing of cached peers to keep their multiaddrs up to date. Applies only when`SOMEGUY_CACHED_ADDR_BOOK` is enabled.
63
63
64
64
Default: `true`
65
65
@@ -71,7 +71,7 @@ Supports two URL formats:
71
71
- Base URL without path: `https://example.com`
72
72
- Full URL with path: `https://example.com/routing/v1/providers`
73
73
74
-
When using the `auto` placeholder (default), endpoints are automatically configured from the network configuration at [`SOMEGUY_AUTOCONF_URL`](#someguy_autoconf_url).
74
+
The `auto` placeholder (default) resolves to endpoints from the network configuration at [`SOMEGUY_AUTOCONF_URL`](#someguy_autoconf_url).
75
75
76
76
Default: `auto`
77
77
@@ -91,11 +91,11 @@ URL formats: same as [`SOMEGUY_PROVIDER_ENDPOINTS`](#someguy_provider_endpoints)
91
91
92
92
Default: `auto`
93
93
94
-
### `SOMEGUY_AUTOCONF`
94
+
### `SOMEGUY_AUTOCONF`
95
95
96
-
Enable or disable automatic configuration (autoconf) of delegated routing endpoints and bootstrap peers.
96
+
Enables automatic configuration (autoconf) of delegated routing endpoints and bootstrap peers.
97
97
98
-
When enabled, the `auto` placeholder in endpoint configuration is replaced with network-recommended values fetched from the autoconf URL.
98
+
When enabled, Someguy replaces the `auto` placeholder in endpoint configuration with network-recommended values fetched from the autoconf URL.
99
99
100
100
Default: `true`
101
101
@@ -113,9 +113,9 @@ Default: `24h`
113
113
114
114
### `SOMEGUY_HTTP_BLOCK_PROVIDER_ENDPOINTS`
115
115
116
-
Comma-separated list of [HTTP trustless gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/)for probing and generating synthetic provider records.
116
+
Comma-separated list of [HTTP trustless gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/)that Someguy probes to synthesize provider records.
117
117
118
-
When the configured gateway responds with HTTP 200 to an HTTP HEAD request for a block (`HEAD /ipfs/{cid}?format=raw`), `FindProviders` returns a provider record containing a PeerID from `SOMEGUY_HTTP_BLOCK_PROVIDER_PEERIDS` and the HTTP gateway endpoint as a multiaddr with `/tls/http` suffix.
118
+
When a configured gateway responds with HTTP 200 to a `HEAD /ipfs/{cid}?format=raw` request, `FindProviders` returns a provider record that contains the matching PeerID from `SOMEGUY_HTTP_BLOCK_PROVIDER_PEERIDS` and the gateway endpoint as a multiaddr with the`/tls/http` suffix.
119
119
120
120
> [!IMPORTANT]
121
121
> When creating a synthetic `/routing/v1` for your gateway, and not a general-purpose routing endpoint, set `SOMEGUY_DHT=disabled` and `SOMEGUY_PROVIDER_ENDPOINTS=""` to disable default DHT and HTTP routers and exclusively use the explicitly defined `SOMEGUY_HTTP_BLOCK_PROVIDER_ENDPOINTS`.
@@ -124,17 +124,15 @@ Default: none
124
124
125
125
### `SOMEGUY_HTTP_BLOCK_PROVIDER_PEERIDS`
126
126
127
-
Comma-separated list of [multibase-encoded peerIDs](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#string-representation)to use in synthetic provider records returned for HTTP providers in `SOMEGUY_HTTP_BLOCK_PROVIDER_ENDPOINTS`. The order of PeerIDs must match the order of endpoints.
127
+
Comma-separated list of [multibase-encoded peerIDs](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#string-representation)that Someguy embeds in synthetic provider records for the HTTP endpoints in `SOMEGUY_HTTP_BLOCK_PROVIDER_ENDPOINTS`. The order of PeerIDs must match the order of endpoints.
128
128
129
-
If no peerIDs are passed but provider endpoints are configured, synthetic PeerIDs will be automatically generated. These are deterministic identifiers derived from SHA256 hashes of the endpoint URLs, used solely for routingsystem compatibility. Since these providers use HTTP trustless gateway protocol rather than libp2p, the PeerIDs are purely synthetic and never participate in any cryptographic operations or peer authentication.
129
+
If you configure provider endpoints without PeerIDs, Someguy generates synthetic PeerIDs automatically, deterministically derived from SHA-256 hashes of the endpoint URLs. These PeerIDs exist only for routing-system compatibility; HTTP trustless gateways never use them for cryptographic operations or peer authentication.
130
130
131
131
Default: none
132
132
133
133
### `SOMEGUY_LIBP2P_LISTEN_ADDRS`
134
134
135
-
Multiaddresses for libp2p host to listen on (comma-separated).
136
-
137
-
Default: `someguy start --help`
135
+
Comma-separated libp2p listen multiaddresses. Someguy binds port `4004` on IPv4 and IPv6 across libp2p's default transports. To see the exact defaults built into this release, run `someguy start --help`.
138
136
139
137
### `SOMEGUY_LIBP2P_CONNMGR_LOW`
140
138
@@ -170,8 +168,7 @@ Default: 0 (50% of the process' limit)
170
168
171
169
### `GOLOG_LOG_LEVEL`
172
170
173
-
Specifies the log-level, both globally and on a per-subsystem basis. Level can
174
-
be one of:
171
+
Sets the log level globally or per subsystem. Levels:
175
172
176
173
*`debug`
177
174
*`info`
@@ -181,9 +178,7 @@ be one of:
181
178
*`panic`
182
179
*`fatal`
183
180
184
-
Per-subsystem levels can be specified with `subsystem=level`. One global level
185
-
and one or more per-subsystem levels can be specified by separating them with
186
-
commas.
181
+
Specify per-subsystem levels as `subsystem=level`. Combine a global level with any number of per-subsystem levels by separating them with commas.
For example, to log structured JSON (for easier parsing):
205
200
@@ -211,29 +206,26 @@ The logging format defaults to `color` when the output is a terminal, and
211
206
212
207
### `GOLOG_FILE`
213
208
214
-
Sets the file to which the logs are saved. By default, they are printed to the standard error output.
209
+
Writes logs to the given file. Defaults to stderr.
215
210
216
211
### `GOLOG_TRACING_FILE`
217
212
218
-
Sets the file to which the tracing events are sent. By default, tracing is disabled.
213
+
Writes tracing events to the given file. Tracing is disabled by default.
219
214
220
-
Warning: Enabling tracing will likely affect performance.
215
+
Warning: tracing affects performance.
221
216
222
217
## Tracing
223
218
224
219
See [tracing.md](tracing.md).
225
220
226
221
### `SOMEGUY_TRACING_AUTH`
227
222
228
-
Optional, setting to non-empty value enables on-demand tracing per-request.
223
+
Setting a non-empty value enables on-demand per-request tracing.
229
224
230
-
The ability to pass `Traceparent` or `Tracestate` headers is guarded by an
231
-
`Authorization` header. The value of the `Authorization` header should match
232
-
the value in the `SOMEGUY_TRACING_AUTH` environment variable.
225
+
To honor a `Traceparent` or `Tracestate` header, Someguy requires the request to carry an `Authorization` header whose value matches `SOMEGUY_TRACING_AUTH`.
233
226
234
227
### `SOMEGUY_SAMPLING_FRACTION`
235
228
236
-
Optional, set to 0 by default.
229
+
Fraction of routing requests to sample (0 to 1). Applied independently of `Traceparent`-based sampling.
237
230
238
-
The fraction (between 0 and 1) of requests that should be sampled.
239
-
This is calculated independently of any Traceparent based sampling.
By default, a prometheus endpoint is exposed by someguy at `http://127.0.0.1:8190/debug/metrics/prometheus`.
3
+
Someguy exposes a Prometheus endpoint at `http://127.0.0.1:8190/debug/metrics/prometheus` by default.
4
4
5
-
It includes default [Prometheus Glient metrics](https://prometheus.io/docs/guides/go-application/)+ someguy-specific listed below.
5
+
The endpoint includes the default [Prometheus Go client metrics](https://prometheus.io/docs/guides/go-application/)plus the Someguy-specific metrics listed below.
6
6
7
7
### Delegated HTTP Routing (`/routing/v1`) server
8
8
9
-
Metric from `boxo/routing/http/server` (used for `/routing/v1` handler) are exposed with `delegated_routing_server_` prefix:
9
+
`boxo/routing/http/server` (the `/routing/v1` handler) exports metrics with the`delegated_routing_server_` prefix:
10
10
11
-
-`delegated_routing_server_http_request_duration_seconds_[bucket|sum|count]{code,handler,method}` - histogram: the latency of the HTTP requests
12
-
-`delegated_routing_server_http_response_size_bytes_[bucket|sum|count]{code,handler,method}` - histogram: the size of the HTTP responses
If someguy is set up as an aggregating proxy for multiple other `/routing/v1` endpoints,
17
-
metrics from `boxo/routing/http/client` are exposed with `someguy_` prefix:
16
+
When Someguy aggregates other `/routing/v1` endpoints, `boxo/routing/http/client` exports metrics with the `someguy_` prefix:
18
17
19
-
-`someguy_routing_http_client_latency_[bucket|sum|count]{code,error,host,operation}` - Histogram: the latency of operations by the routing HTTP client:
20
-
-`someguy_routing_http_client_length_[bucket|sum|count]{host,operation}` - Histogram: the number of elements in a response collection
18
+
-`someguy_routing_http_client_latency_[bucket|sum|count]{code,error,host,operation}`: histogram of operation latency
19
+
-`someguy_routing_http_client_length_[bucket|sum|count]{host,operation}`: histogram of response collection size
21
20
22
-
### Someguy Caches
21
+
### Someguy caches
23
22
24
-
-`someguy_cached_addr_book_probe_duration_seconds_[bucket|sum|count]` - Histogram: duration of peer probing operations in seconds
25
-
-`someguy_cached_router_peer_addr_lookups{cache,origin}` - Counter: number of peer addr info lookups per origin and cache state
26
-
-`someguy_cached_addr_book_peer_state_size` - Gauge: number of peers object currently in the peer state
23
+
-`someguy_cached_addr_book_probe_duration_seconds_[bucket|sum|count]`: histogram of peer-probing duration in seconds
24
+
-`someguy_cached_addr_book_probed_peers{result}`: counter of probed peers, labeled `online` or `offline`
25
+
-`someguy_cached_addr_book_peer_state_size`: gauge of peers currently tracked in peer state
26
+
-`someguy_cached_router_peer_addr_lookups{cache,origin}`: counter of peer address-info lookups per origin and cache state
Copy file name to clipboardExpand all lines: docs/tracing.md
+10-16Lines changed: 10 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,37 +1,31 @@
1
1
## Tracing
2
2
3
-
Tracing across the stack follows, as much as possible, the [Open Telemetry]
4
-
specifications. Configuration environment variables are specified in the
5
-
[OpenTelemetry Environment Variable Specification] where possible. The
6
-
[Boxo Tracing] documentation is the basis for tracing here.
3
+
Someguy follows the [Open Telemetry] specifications across the stack. Where possible, it reads the environment variables defined in the [OpenTelemetry Environment Variable Specification]. Tracing builds on [Boxo Tracing].
7
4
8
5
> [!NOTE]
9
-
> A major distinction from the more [general tracing enabled in boxo][Boxo Tracing] is that when
10
-
> tracing is enabled it is restricted to flows through HTTP Gateway requests, rather
11
-
> than also included background processes.
6
+
> Unlike the [general tracing in boxo][Boxo Tracing], Someguy traces only inbound HTTP routing requests, not background processes.
12
7
13
-
### Fractional Sampling
8
+
### Fractional sampling
14
9
15
-
To sample a % of requests set [`SOMEGUY_SAMPLING_FRACTION`](environment-variables.md#someguy_sampling_fraction) to a value between `0` and `1`.
10
+
To sample a fraction of requests, set [`SOMEGUY_SAMPLING_FRACTION`](environment-variables.md#someguy_sampling_fraction) to a value between `0` and `1`.
16
11
17
-
### Per Request
12
+
### Per-request
18
13
19
-
Per-request tracing is possible when a non-empty [`SOMEGUY_TRACING_AUTH`](environment-variables.md#someguy_tracing_auth) is set in Someguy and when there are both valid
20
-
[Authorization](headers.md#authorization) and [`Traceparent`](headers.md#traceparent) HTTP headers passed in the request.
14
+
Per-request tracing activates when [`SOMEGUY_TRACING_AUTH`](environment-variables.md#someguy_tracing_auth) is set and the request carries both an `Authorization` header matching that value and a valid `Traceparent` header.
21
15
22
-
### Per-request tracing example:
16
+
### Per-request tracing example
23
17
24
18
```console
25
19
$ export SOMEGUY_TRACING_AUTH=CHANGEME-tracing-auth-secret # use value from Someguy config
0 commit comments