Feat/auto schemas (#48)

* use auto generated schemas

* go version bump and dependencies upgrade

* clarify some error messages

---------

Co-authored-by: yusing <yusing@6uo.me>

schemas/config/access_log.ts

@@ -0,0 +1,66 @@
+import { CIDR, HTTPHeader, HTTPMethod, StatusCodeRange, URI } from "../types";
+
+export const ACCESS_LOG_FORMATS = ["combined", "common", "json"] as const;
+
+export type AccessLogFormat = (typeof ACCESS_LOG_FORMATS)[number];
+
+export type AccessLogConfig = {
+  /**
+   * The size of the buffer.
+   *
+   * @minimum 0
+   * @default 65536
+   * @TJS-type integer
+   */
+  buffer_size?: number;
+  /** The format of the access log.
+   *
+   * @default "combined"
+   */
+  format?: AccessLogFormat;
+  /* The path to the access log file. */
+  path: URI;
+  /* The access log filters. */
+  filters?: AccessLogFilters;
+  /* The access log fields. */
+  fields?: AccessLogFields;
+};
+
+export type AccessLogFilter<T> = {
+  /** Whether the filter is negative.
+   *
+   * @default false
+   */
+  negative?: boolean;
+  /* The values to filter. */
+  values: T[];
+};
+
+export type AccessLogFilters = {
+  /* Status code filter. */
+  status_code?: AccessLogFilter<StatusCodeRange>;
+  /* Method filter. */
+  method?: AccessLogFilter<HTTPMethod>;
+  /* Host filter. */
+  host?: AccessLogFilter<string>;
+  /* Header filter. */
+  headers?: AccessLogFilter<HTTPHeader>;
+  /* CIDR filter. */
+  cidr?: AccessLogFilter<CIDR>;
+};
+
+export const ACCESS_LOG_FIELD_MODES = ["keep", "drop", "redact"] as const;
+export type AccessLogFieldMode = (typeof ACCESS_LOG_FIELD_MODES)[number];
+
+export type AccessLogField = {
+  default?: AccessLogFieldMode;
+  config: {
+    [key: string]: AccessLogFieldMode;
+  };
+};
+
+export type AccessLogFields = {
+  header?: AccessLogField;
+  query?: AccessLogField;
+  cookie?: AccessLogField;
+};

schemas/config/autocert.ts

@@ -0,0 +1,91 @@
+import { DomainOrWildcards as DomainsOrWildcards, Email } from "../types";
+
+export const AUTOCERT_PROVIDERS = [
+  "local",
+  "cloudflare",
+  "clouddns",
+  "duckdns",
+  "ovh",
+] as const;
+
+export type AutocertProvider = (typeof AUTOCERT_PROVIDERS)[number];
+
+export type AutocertConfig =
+  | LocalOptions
+  | CloudflareOptions
+  | CloudDNSOptions
+  | DuckDNSOptions
+  | OVHOptionsWithAppKey
+  | OVHOptionsWithOAuth2Config;
+
+export interface AutocertConfigBase {
+  /* ACME email */
+  email: Email;
+  /* ACME domains */
+  domains: DomainsOrWildcards;
+  /* ACME certificate path */
+  cert_path?: string;
+  /* ACME key path */
+  key_path?: string;
+}
+
+export interface LocalOptions extends AutocertConfigBase {
+  provider: "local";
+}
+
+export interface CloudflareOptions extends AutocertConfigBase {
+  provider: "cloudflare";
+  options: { auth_token: string };
+}
+
+export interface CloudDNSOptions extends AutocertConfigBase {
+  provider: "clouddns";
+  options: {
+    client_id: string;
+    email: Email;
+    password: string;
+  };
+}
+
+
+export interface DuckDNSOptions extends AutocertConfigBase {
+  provider: "duckdns";
+  options: {
+    token: string;
+  };
+}
+
+export const OVH_ENDPOINTS = [
+  "ovh-eu",
+  "ovh-ca",
+  "ovh-us",
+  "kimsufi-eu",
+  "kimsufi-ca",
+  "soyoustart-eu",
+  "soyoustart-ca",
+] as const;
+
+export type OVHEndpoint = (typeof OVH_ENDPOINTS)[number];
+
+export interface OVHOptionsWithAppKey extends AutocertConfigBase {
+  provider: "ovh";
+  options: {
+    application_secret: string;
+    consumer_key: string;
+    api_endpoint?: OVHEndpoint;
+    application_key: string;
+  };
+}
+
+export interface OVHOptionsWithOAuth2Config extends AutocertConfigBase {
+  provider: "ovh";
+  options: {
+    application_secret: string;
+    consumer_key: string;
+    api_endpoint?: OVHEndpoint;
+    oauth2_config: {
+      client_id: string;
+      client_secret: string;
+    };
+  };
+}

schemas/config/config.ts

@@ -0,0 +1,52 @@
+import { DomainNames } from "../types";
+import { AutocertConfig } from "./autocert";
+import { EntrypointConfig } from "./entrypoint";
+import { HomepageConfig } from "./homepage";
+import { Providers } from "./providers";
+
+export type Config = {
+  /** Optional autocert configuration
+   *
+   * @examples require(".").autocertExamples
+   */
+  autocert?: AutocertConfig;
+  /* Optional entrypoint configuration */
+  entrypoint?: EntrypointConfig;
+  /* Providers configuration (include file, docker, notification) */
+  providers: Providers;
+  /** Optional list of domains to match
+   *
+   * @minItems 1
+   * @examples require(".").matchDomainsExamples
+   */
+  match_domains?: DomainNames;
+  /* Optional homepage configuration */
+  homepage?: HomepageConfig;
+  /**
+   * Optional timeout before shutdown
+   * @default 3
+   * @minimum 1
+   */
+  timeout_shutdown?: number;
+};
+
+export const autocertExamples = [
+  { provider: "local" },
+  {
+    provider: "cloudflare",
+    email: "abc@gmail",
+    domains: ["example.com"],
+    options: { auth_token: "c1234565789-abcdefghijklmnopqrst" },
+  },
+  {
+    provider: "clouddns",
+    email: "abc@gmail",
+    domains: ["example.com"],
+    options: {
+      client_id: "c1234565789",
+      email: "abc@gmail",
+      password: "password",
+    },
+  },
+];
+export const matchDomainsExamples = ["example.com", "*.example.com"] as const;

schemas/config/entrypoint.ts

@@ -0,0 +1,47 @@
+import { MiddlewareCompose } from "../middlewares/middleware_compose";
+import { AccessLogConfig } from "./access_log";
+
+export type EntrypointConfig = {
+  /** Entrypoint middleware configuration
+   *
+   * @examples require(".").middlewaresExamples
+   */
+  middlewares: MiddlewareCompose;
+  /** Entrypoint access log configuration
+   *
+   * @examples require(".").accessLogExamples
+   */
+  access_log?: AccessLogConfig;
+};
+
+export const accessLogExamples = [
+  {
+    path: "/var/log/access.log",
+    format: "combined",
+    filters: {
+      status_codes: {
+        values: ["200-299"],
+      },
+    },
+    fields: {
+      headers: {
+        default: "keep",
+        config: {
+          foo: "redact",
+        },
+      },
+    },
+  },
+] as const;
+
+export const middlewaresExamples = [
+  {
+    use: "RedirectHTTP",
+  },
+  {
+    use: "CIDRWhitelist",
+    allow: ["127.0.0.1", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
+    status: 403,
+    message: "Forbidden",
+  },
+] as const;

schemas/config/homepage.ts

@@ -0,0 +1,7 @@
+export type HomepageConfig = {
+  /**
+   * Use default app categories (uses docker image name)
+   * @default true
+   */
+  use_default_categories: boolean;
+};

schemas/config/notification.ts

@@ -0,0 +1,67 @@
+import { URL } from "../types";
+
+export const NOTIFICATION_PROVIDERS = ["webhook", "gotify"] as const;
+
+export type NotificationProvider = (typeof NOTIFICATION_PROVIDERS)[number];
+
+export type NotificationConfig = {
+  /* Name of the notification provider */
+  name: string;
+  /* URL of the notification provider */
+  url: URL;
+};
+
+export interface GotifyConfig extends NotificationConfig {
+  provider: "gotify";
+  /* Gotify token */
+  token: string;
+}
+
+export const WEBHOOK_TEMPLATES = ["discord"] as const;
+export const WEBHOOK_METHODS = ["POST", "GET", "PUT"] as const;
+export const WEBHOOK_MIME_TYPES = [
+  "application/json",
+  "application/x-www-form-urlencoded",
+  "text/plain",
+] as const;
+export const WEBHOOK_COLOR_MODES = ["hex", "dec"] as const;
+
+export type WebhookTemplate = (typeof WEBHOOK_TEMPLATES)[number];
+export type WebhookMethod = (typeof WEBHOOK_METHODS)[number];
+export type WebhookMimeType = (typeof WEBHOOK_MIME_TYPES)[number];
+export type WebhookColorMode = (typeof WEBHOOK_COLOR_MODES)[number];
+
+export interface WebhookConfig extends NotificationConfig {
+  provider: "webhook";
+  /**
+   * Webhook template
+   *
+   * @default "discord"
+   */
+  template?: WebhookTemplate;
+  /* Webhook token */
+  token?: string;
+  /**
+   * Webhook message (usally JSON),
+   * required when template is not defined
+   */
+  payload?: string;
+  /**
+   * Webhook method
+   *
+   * @default "POST"
+   */
+  method?: WebhookMethod;
+  /**
+   * Webhook mime type
+   *
+   * @default "application/json"
+   */
+  mime_type?: WebhookMimeType;
+  /**
+   * Webhook color mode
+   *
+   * @default "hex"
+   */
+  color_mode?: WebhookColorMode;
+}

schemas/config/providers.ts

@@ -0,0 +1,46 @@
+import { URI, URL } from "../types";
+import { GotifyConfig, WebhookConfig } from "./notification";
+
+export type Providers = {
+  /** List of route definition files to include
+   *
+   * @minItems 1
+   * @examples require(".").includeExamples
+   * @items.pattern ^[\w\d\-_]+\.(yaml|yml)$
+   */
+  include?: URI[];
+  /** Name-value mapping of docker hosts to retrieve routes from
+   *
+   * @minProperties 1
+   * @examples require(".").dockerExamples
+   * @items.pattern ^((\w+://)[^\s]+)|\$DOCKER_HOST$
+   */
+  docker?: { [name: string]: URL };
+  /** List of notification providers
+   *
+   * @minItems 1
+   * @examples require(".").notificationExamples
+   */
+  notification?: (WebhookConfig | GotifyConfig)[];
+};
+
+export const includeExamples = ["file1.yml", "file2.yml"] as const;
+export const dockerExamples = [
+  { local: "$DOCKER_HOST" },
+  { remote: "tcp://10.0.2.1:2375" },
+  { remote2: "ssh://root:1234@10.0.2.2" },
+] as const;
+export const notificationExamples = [
+  {
+    name: "gotify",
+    provider: "gotify",
+    url: "https://gotify.domain.tld",
+    token: "abcd",
+  },
+  {
+    name: "discord",
+    provider: "webhook",
+    template: "discord",
+    url: "https://discord.com/api/webhooks/1234/abcd",
+  },
+] as const;