Observatory: add reliable one-shot outbound probe batches and result notifications

[eliotcougar]

Summary

This PR adds an embedder-oriented Observatory API for running a finite, bounded batch of outbound probes through one already-created Xray instance.

It is intended for applications that need to measure many outbounds on demand but cannot afford to create one Xray process or core instance per outbound. A caller can provide the outbound tags, concurrency limit, and sample count, receive progressive result notifications, and retain the measurements completed by the current batch even if it is cancelled or interrupted.

The PR also adds Observatory result-update notifications and probe-deadline reporting. Besides supporting responsive one-shot probing, these APIs provide the coordination required by downstream cached-route warm-start implementations.

Motivation

Applications commonly need to display the delay of many configured outbounds or evaluate policy-group candidates in one user-initiated operation.

Creating an independent Xray process for every outbound can provide isolation, but it is often impractical:

• Process and core startup are expensive.
• Each instance duplicates configuration, routing, DNS, transport, and runtime state.
• Memory and CPU usage grow with the number of outbounds.
• Mobile operating systems may limit or kill a large group of temporary processes.
• Startup and IPC overhead can dominate short delay measurements.
• Running multiple temporary cores in one process is undesirable and can corrupt the main core.

This feature provides a middle ground: one disposable Xray instance can contain all required outbounds and probe them concurrently with bounded resource usage. Embedders can therefore perform reliable bulk probing without requiring one process per outbound and without running multiple Xray cores in the same process.

Public API

The following optional extension interfaces are added:

ObservatoryBatchProbe

type ObservatoryBatchProbe interface {
    Observatory

    ProbeOutboundsDeadline(
        tags []string,
        maxConcurrency int,
        samples int,
    ) (time.Duration, error)

    ProbeOutbounds(
        ctx context.Context,
        tags []string,
        maxConcurrency int,
        samples int,
    ) error
}

ProbeOutbounds runs a finite batch through the outbounds already registered in the current Xray instance.

The caller controls:

• Which outbound tags are tested.
• The maximum number of concurrent probe workers.
• The number of samples collected for each outbound.
• Cancellation through context.Context.

ProbeOutboundsDeadline reports the configured worst-case probe budget for the same parameters. This allows an embedding application to add only its own process-management grace period instead of relying on an arbitrary fixed timeout.

ObservatoryUpdateNotifier

type ObservatoryUpdateNotifier interface {
    SubscribeObservationUpdates() (
        updates <-chan struct{},
        unsubscribe func(),
    )
}

The notifier publishes a coalesced, non-blocking signal whenever observable results change.

The signal is deliberately not the result itself and is not a routing decision. After receiving it, a consumer queries GetObservation or reevaluates its balancer. This keeps delivery lightweight, prevents slow subscribers from blocking probe workers, and avoids exposing mutable internal state.

ObservatoryProbeDeadline

type ObservatoryProbeDeadline interface {
    ObservationProbeDeadline() time.Duration
}

This reports the longest expected time before a scheduled Observatory can publish its initial result. Batch callers use ProbeOutboundsDeadline instead.

The interface is implemented by both the regular Observatory and BurstObservatory.

One-shot probing behavior

The BurstObservatory implementation now supports one-shot batches with the following behavior:

• One Xray instance probes all requested outbounds.
• Work is bounded by maxConcurrency.
• Samples for a given outbound are collected serially by its worker.
• Multiple outbounds can be measured concurrently.
• Duplicate tags are normalized.
• Empty tags, missing handlers, invalid concurrency, invalid sample counts, and excessive retained work are rejected before the batch begins.
• Only one batch may run on an observer at a time.
• A batch cannot overlap a manual Check.
• Closing the observer cancels and waits for the active batch.

A one-shot observer must be configured without scheduled subject selectors. Scheduled observation and one-shot probing are intentionally kept mutually exclusive so their result sets and lifecycles cannot race.

The current implementation also applies defensive limits to active workers, samples per outbound, and total retained measurements. These are safety limits for untrusted or erroneous embedder parameters, not recommended operating values.

Progressive and partial results

One-shot probing does not wait for every outbound to finish before exposing useful information.

After each completed sample:

1. The current batch result is updated.
2. A coalesced notification is published.
3. The embedder may call GetObservation.
4. The user interface can immediately display the current average and availability information.

The batch begins with an empty result set. There is no previous batch snapshot: only measurements produced by the current invocation are exposed. Outbounds that have not produced a sample yet are absent.

Samples used by the one-shot batch are non-expiring because the intended lifecycle is:

1. Create one dedicated Xray instance.
2. Run one batch.
3. consume its final or partial snapshot;
4. discard the instance or containing process.

After ProbeOutbounds returns, GetObservation retains every sample completed by that invocation:

• A nil error means the requested batch completed.
• A non-nil error means the result may be partial.
• Cancellation preserves samples completed before cancellation.
• Core shutdown preserves already published samples.
• Network loss preserves completed measurements and does not mark all unfinished outbounds as dead.

This makes partial progress useful while avoiding misleading synthetic failures.

Network-loss handling

A failed outbound and an unavailable underlying network are different conditions.

When an outbound probe fails and a connectivity check is configured, the implementation checks direct connectivity using the same cancellable instance context. If the underlying network is unavailable:

• The remaining batch is cancelled.
• Completed samples are retained.
• Unfinished outbounds are not synthesized as failed.
• ErrObservatoryProbeNetworkUnavailable is returned.

This allows an embedding application to report that the test was interrupted by network loss rather than incorrectly presenting every remaining proxy as unavailable.

Probe and connectivity dials honor cancellation at their individual deadlines, including tagged outbound dials. This prevents timed-out requests from remaining active after their result is no longer useful.

Deadline calculation

Batch deadlines are derived from the actual probing parameters:

• Configured per-request timeout.
• Number of unique outbound tags.
• Maximum concurrency.
• Number of samples per outbound.
• Number of worker waves.
• An additional connectivity-check timeout where applicable.

Overflow and invalid values are rejected.

Scheduled Observatory deadlines are also exposed for regular and burst implementations. This gives downstream applications a configuration-aware safety boundary rather than forcing them to guess how long an initial observation should take.

Warm-start support

The notification and scheduled-deadline additions are also required by downstream route warm-start implementations.

A mobile application may remember the last viable policy-group target for a particular network. After the underlying network changes, it can temporarily restore that target while the newly created core's Observatory performs its first fresh probe cycle.

A correct warm-start flow requires two pieces of information from Xray:

1. An event indicating that Observatory results actually changed.
2. A configuration-derived upper bound for the initial probe cycle.

ObservatoryUpdateNotifier allows the embedder to react when a real result changes instead of polling Observatory state every few hundred milliseconds. After a notification, the embedder reevaluates the balancer, stores the fresh viable target, and releases its temporary warm-route override.

ObservatoryProbeDeadline gives the embedder a sensible fallback deadline if no viable update is produced. For regular Observatory it accounts for concurrent or sequential probing. For BurstObservatory it reflects the configured health-ping timeout and optional connectivity check.

The update dispatcher is instance-scoped, supports multiple subscribers, coalesces unread notifications, and cannot be blocked by a slow consumer.

These APIs do not implement or persist a route cache inside Xray. Network identification and cache policy remain the embedding application's responsibility.

Compatibility

• The existing Observatory and BurstObservatory interfaces retain their existing methods.
• Batch probing, notifications, and deadline reporting are exposed through optional extension interfaces.
• Existing embedders do not need to adopt the new APIs.
• Existing scheduled Observatory and BurstObservatory operation remains available.
• One-shot batch state is isolated from scheduled and manual probe state.
• GetObservation returns stable snapshots rather than exposing mutable internal result objects.
• No persistent cache or new configuration schema is introduced.

This PR is independent of XTLS/Xray-core#6483, whose reduced scope concerns instance-owned system dialer state.

Downstream use

This work is intended as the Xray-core prerequisite for:

• 2dust/AndroidLibXrayLite#200
• 2dust/v2rayNG#5905

AndroidLibXrayLite wraps the batch API for mobile embedders. v2rayNG uses it in one focused disposable Android process containing one Xray instance, allowing multiple profiles and policy-group candidates to be probed concurrently without creating one process per outbound.

The same API can be used by other desktop, mobile, or embedded clients that need efficient bulk outbound measurements.

Testing

The implementation includes coverage for:

• Bounded worker concurrency.
• Multiple samples per outbound.
• Parameter and outbound-tag validation.
• Batch deadline calculation and overflow handling.
• Progressive update delivery.
• Subscriber isolation and unsubscribe behavior.
• Stable observation snapshots.
• Empty batches.
• Cancellation and core shutdown.
• Partial-result retention.
• Underlying network loss.
• Per-probe deadline cancellation.
• Isolation from scheduled and manual probes.
• Non-expiring one-shot samples.
• Correct RTT statistics on 32-bit targets.

Focused Observatory and extension tests pass, including race-detector runs for the BurstObservatory and extension packages. A release-style Xray executable also builds successfully.

[Fangliding]

不打算扩展这个接口了
不要把一堆AI pr拿上来