lspf 0.5.0

A Rust framework for building extensible LSP language servers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

//! lspf — a Rust framework for building extensible LSP language servers.
//!
//! See `CONTEXT.md` and `docs/adr/` at the repository root for the domain
//! language and the architectural decisions that shape this crate.

// A protocol-only feature row intentionally has no serving engine. The
// public registration and protocol types remain useful there, while the
// engine-owned internals are necessarily dormant until a Transport selects a
// runtime. All other warnings stay denied in CI for this row.
#![cfg_attr(
    all(not(target_arch = "wasm32"), not(feature = "runtime-tokio")),
    allow(dead_code)
)]

#[cfg(all(target_arch = "wasm32", not(feature = "wasm")))]
compile_error!(
    "the wasm32 target requires the `wasm` feature; \
     build with `--no-default-features --features worker-channel`, \
     or `--no-default-features --features wasm` plus your transports"
);

// The worker-channel adapter wraps a browser or Node Worker MessagePort: it
// only exists inside a Worker on `wasm32-unknown-unknown`.
#[cfg(all(feature = "worker-channel", not(target_arch = "wasm32")))]
compile_error!("the `worker-channel` feature requires the wasm32 target");

// Native socket adapters depend on Tokio's reactor and are deliberately not
// part of the Worker-hosted WASM surface. Keep these diagnostics here, next to
// target/feature contract, so an unsupported feature combination fails for a
// reason that tells the caller how to fix it.
#[cfg(all(target_arch = "wasm32", feature = "tcp"))]
compile_error!("the `tcp` feature is not supported on the wasm32 target");

#[cfg(all(target_arch = "wasm32", feature = "websocket"))]
compile_error!("the `websocket` feature is not supported on the wasm32 target");

mod builder;
mod capability;
mod client;
mod codec;
mod context;
mod documents;
// Serving needs an executor: the engine exists wherever a runtime is
// available (ADR 0020). On native targets that is the `runtime-tokio`
// feature; on wasm32 the `wasm` feature, which the check above enforces.
#[cfg(any(feature = "runtime-tokio", target_arch = "wasm32"))]
mod engine;
mod error;
pub mod features;
mod file_provider;
mod progress;
#[cfg(feature = "proposed")]
pub mod proposed;
mod raw;
mod runtime;
mod service;
mod sync;
mod transport;
mod uri_key;
mod workspace;

#[cfg(all(test, not(target_arch = "wasm32")))]
mod test_util;

pub mod types {
    //! LSP protocol types — re-exported from `lsp-types` per ADR 0014.
    pub use lsp_types::*;
}

/// Compiles the Rust in the repository's user-facing Markdown as doc-tests, so
/// a quickstart or a guide example cannot drift from the surface it documents.
/// The module exists only under `cargo test --doc`; nothing here is part of
/// the public API.
#[cfg(doctest)]
mod markdown {
    #[doc = include_str!("../../../README.md")]
    pub struct Readme;

    #[doc = include_str!("../../../README.zh-CN.md")]
    pub struct ReadmeZhCn;

    #[doc = include_str!("../../../docs/guides/features-and-workspace.md")]
    pub struct FeaturesAndWorkspaceGuide;

    #[doc = include_str!("../../../docs/guides/outgoing-client.md")]
    pub struct OutgoingClientGuide;

    #[doc = include_str!("../../../docs/guides/migrating-to-0.4.md")]
    pub struct MigratingTo04Guide;

    #[doc = include_str!("../../../docs/guides/transports.md")]
    pub struct TransportsGuide;
}

#[doc(hidden)]
pub use builder::SharedHandler;
pub use builder::{InitializeRegistrar, Server, ServerBuilder};
pub use client::{Client, TelemetryEventParams};
pub use context::Context;
pub use documents::{Document, DocumentsView, PositionEncoding};
#[cfg(any(feature = "runtime-tokio", target_arch = "wasm32"))]
pub use engine::Outcome;
pub use error::{BuildError, ClientError, Error, LspError, ProgressError, Result};
pub use features::{FeatureSpec, NotificationFeatureSpec};
#[cfg(target_arch = "wasm32")]
pub use file_provider::EmptyFileProvider;
pub use file_provider::{FileProvider, MemoryFileProvider};
#[cfg(all(not(target_arch = "wasm32"), feature = "runtime-tokio"))]
pub use file_provider::{OsFileProvider, OsFileProviderBuilder};
pub use progress::{ProgressHandle, ProgressOptions};
pub use raw::{JsonRpcError, RawMessage, RequestId};
#[doc(hidden)]
pub use runtime::{TaskFuture, TaskSend};
pub use service::{CallKind, IncomingCall, Layer, Next, ServiceFuture, ServiceResult};
#[cfg(all(feature = "stdio", not(target_arch = "wasm32")))]
pub use transport::{StdioBuilder, StdioReader, StdioTransport, StdioWriter, stdio};
#[cfg(all(feature = "tcp", not(target_arch = "wasm32")))]
pub use transport::{TcpBuilder, TcpReader, TcpTransport, TcpWriter, tcp};
pub use transport::{Transport, TransportError, TransportReader, TransportWriter};
#[cfg(all(feature = "websocket", not(target_arch = "wasm32")))]
pub use transport::{
    WebSocketBuilder, WebSocketReader, WebSocketTransport, WebSocketWriter, websocket,
};
#[cfg(all(feature = "worker-channel", target_arch = "wasm32"))]
pub use transport::{
    WorkerChannelBuilder, WorkerChannelReader, WorkerChannelTransport, WorkerChannelWriter,
    worker_channel,
};
pub use workspace::{Workspace, WorkspaceError};

/// Cancellation primitive passed to every request handler (ADR 0007).
pub use tokio_util::sync::CancellationToken;

/// Cap on calls in flight inside the user Layer chain when a [`Server`] does
/// not set its own with [`ServerBuilder::concurrency_limit`] (ADR 0012).
///
/// The cap is connection policy, so it belongs to the built [`Server`] that
/// owns the connection rather than to the `Transport` it is served over.
pub const DEFAULT_CONCURRENCY_LIMIT: usize = 64;

/// Outbound queue depth at which the engine warns once per upward crossing
/// when a [`Server`] does not set its own with
/// [`ServerBuilder::outbound_warning_threshold`].
///
/// The queue itself stays unbounded: the threshold only controls when
/// sustained depth produces a warning, never whether a message is sent.
pub const DEFAULT_OUTBOUND_WARNING_THRESHOLD: usize = 1024;