language-server: update global option descriptions and suggestions

server/src/globalOptions.ts

@@ -4,109 +4,115 @@ import { CompletionItemKind } from "vscode-languageserver";
 export const completions = [
  {
  label: "debug",
- detail: "Enables debug mode, which sets all log levels to debug (unless otherwise specified).",
+ detail: "Enables debug mode, which sets all log levels to debug (unless otherwise specified)",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "http_port",
- detail: "Sets the port the server uses for HTTP.",
+ detail: "Sets the port the server uses for HTTP",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "https_port",
- detail: "Sets the port the server uses for HTTPS.",
+ detail: "Sets the port the server uses for HTTPS",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "default_sni",
- detail: "Sets a default TLS ServerName for when clients do not use SNI in their ClientHello.",
+ detail: "Sets a default TLS ServerName for when clients do not use SNI in their ClientHello",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "order",
- detail: "Change the order in which HTTP handler directive(s) will be exeucted.",
+ detail: "Change the order in which HTTP handler directive(s) will be exeucted",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "experimental_http3",
- detail: "Enable experimental HTTP/3 support.",
+ detail: "Enable experimental HTTP/3 support",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "storage",
- detail: "Configure Caddy's internal storage mechanism.",
+ detail: "Configure Caddy's internal storage mechanism",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "acme_ca",
- detail: "Set the URL used for ACME.",
+ detail: "Set the URL used for ACME",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "acme_ca_root",
- detail: "Set a trusted root certificate for ACME that is not in the system trust store.",
+ detail: "Set a trusted root certificate for ACME that is not in the system trust store",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "acme_eab",
- detail: "Sets an External Account Binding to use for all ACME transactions.",
+ detail: "Sets an External Account Binding to use for all ACME transactions",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "acme_dns",
- detail: "Configure the DNS challenge to be used for ACME transactions.",
+ detail: "Configure the DNS challenge to be used for ACME transactions",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "email",
- detail: "",
+ detail: "Email address used for ACME transactions",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "admin",
- detail: "",
+ detail: "Customize the Admin API endpoint",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "on_demand_tls",
- detail: "",
+ detail: "Configure On-Demand TLS",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "local_certs",
- detail: "",
+ detail: "Causes all certificates to be issued internally by default",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "key_type",
- detail: "",
+ detail: "Specifies the type of key to generate for TLS certificates",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "auto_https",
- detail: "",
+ detail: "Configure automatic HTTPS",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
  {
  label: "cert_issuer",
- detail: "",
+ detail: "Defines the issuer (or source) of TLS certificates.",
+ kind: CompletionItemKind.Constant,
+ data: 1,
+ },
+ {
+ label: "servers",
+ detail: "Customizes HTTP servers",
  kind: CompletionItemKind.Constant,
  data: 1,
  },
@@ -116,6 +122,7 @@ interface Descriptions {
  [key: string]: string
 }
 
+// TODO: Improve descriptions, follow the layout for directives.
 export const descriptions: Descriptions = {
  "debug": "**debug** enables debug mode, which sets all log levels to debug (unless otherwise specified).",
  "http_port": "**http_port** is the port for the server to use for HTTP. For internal use only; does not change the HTTP port for clients. Default: 80",
@@ -129,10 +136,11 @@ export const descriptions: Descriptions = {
  "acme_eab": "**acme_eab** specifies an External Account Binding to use for all ACME transactions.",
  "acme_dns": "**acme_dns** configures the DNS challenge to use for all ACME transactions.",
  "email": "**email** is your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates.",
- "admin": "**admin**",
- "on_demand_tls": "**on_demand_tls**",
+ "admin": "**admin** Customizes the [admin API endpoint](https://caddyserver.com/docs/api). If off, then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server.",
+ "on_demand_tls": "**on_demand_tls** configures [On-Demand TLS](https://caddyserver.com/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [on_demand `tls` subdirective](https://caddyserver.com/docs/caddyfile/directives/tls#syntax)). Highly recommended if using in production environments, to prevent abuse.",
  "local_certs": "**local_certs** causes all certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful in development environments.",
  "key_type": "**key_type** specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it.",
  "auto_https": "**auto_https** configure automatic HTTPS. It can either disable it entirely (`off`) or disable only HTTP-to-HTTPS redirects (`disable_redirects`). See the [Automatic HTTPS](https://caddyserver.com/docs/automatic-https) page for more details.",
  "cert_issuer": "**cert_issuer** defines the issuer (or source) of TLS certificates.",
+ "servers": "**servers** Customizes [HTTP servers](https://caddyserver.com/docs/json/apps/http/servers) with settings that potentially span multiple sites and thus can't be rightly configured in site blocks. These options affect the listener/socket, or other behavior beneath the HTTP layer.",
 };

server/src/server.ts

@@ -150,6 +150,11 @@ async function validateTextDocument(document: TextDocument): Promise<void> {
  const map = new Map();
  options.forEach(a => map.set(a.name, (map.get(a.name) || 0) + 1));
  options.filter(a => map.get(a.name) > 1).forEach((a: Option) => {
+ // servers is the only option that would require having duplicates.
+ if (a.name === "servers") {
+ return;
+ }
+
  diagnostics.push({
  severity: DiagnosticSeverity.Warning,
  range: a.range,