///|
pub suberror OpenApiError {
  InvalidPath(String)
  InvalidSchema(String)
  DuplicateOperation(String)
}

///|
priv struct OpenApiRoute {
  url : String
  title : String
  version : String
}

///|
/// Export routes and their optional contracts without invoking converters or
/// handlers. Routes without a contract use an undocumented default response.
pub fn Router::generate_openapi(
  self : Router,
  title~ : String,
  version~ : String,
) -> @json.Json raise OpenApiError {
  let ctx = SchemaContext::new(None)
  let paths : Map[String, @json.Json] = Map([])
  let templates : Map[String, (String, Array[String])] = Map([])
  for route in self.routes {
    let segments : Array[String] = []
    let shape : Array[String] = []
    let names : Array[String] = []
    let catch_all : Array[Bool] = []
    for segment in route.path.split("/").filter(s => !s.is_empty()) {
      let capture = if segment is [':', .. name] {
        Some((name.to_owned(), false))
      } else if segment is ['*', .. name] {
        Some((if name.is_empty() { "rest" } else { name.to_owned() }, true))
      } else {
        None
      }
      if capture is Some((name, rest)) {
        guard !name.is_empty() &&
          !name.contains("{") &&
          !name.contains("}") &&
          !names.contains(name) else {
          raise InvalidPath(route.path)
        }
        names.push(name)
        catch_all.push(rest)
        segments.push("{\{name}}")
        shape.push("{}")
        if rest {
          break
        }
      } else {
        guard !segment.contains("{") && !segment.contains("}") else {
          raise InvalidPath(route.path)
        }
        segments.push(segment.to_owned())
        shape.push(segment.to_owned())
      }
    }
    let shape = "/" + shape.join("/")
    // OpenAPI forbids separate paths that differ only in capture names.
    // Reuse the first spelling for all operations on the same path shape.
    let (path, parameter_names) = if templates.get(shape) is Some(template) {
      template
    } else {
      let path = "/" + segments.join("/")
      templates[shape] = (path, names)
      (path, names)
    }
    let operation = route.openapi_operation(
      ctx, names, parameter_names, catch_all,
    )
    let item = if paths.get(path) is Some(Object(item)) {
      item
    } else {
      Map([])
    }
    let verb = match route.meth {
      Get => "get"
      Head => "head"
      Post => "post"
      Put => "put"
      Delete => "delete"
      Options => "options"
      Trace => "trace"
      Patch => "patch"
      Connect => "CONNECT"
    }
    if route.meth == Connect {
      let additional = if item.get("additionalOperations")
        is Some(Object(items)) {
        items
      } else {
        Map([])
      }
      guard !additional.contains(verb) else {
        raise DuplicateOperation("\{verb} \{path}")
      }
      additional[verb] = @json.Json::object(operation)
      item["additionalOperations"] = @json.Json::object(additional)
    } else {
      guard !item.contains(verb) else {
        raise DuplicateOperation("\{verb} \{path}")
      }
      item[verb] = @json.Json::object(operation)
    }
    paths[path] = @json.Json::object(item)
  }
  let document : Map[String, @json.Json] = {
    "openapi": "3.2.1",
    "info": { "title": title, "version": version },
    "paths": @json.Json::object(paths),
  }
  if ctx.finish() is Some(components) {
    document["components"] = components
  }
  @json.Json::object(document)
}

///|
/// Configure an OpenAPI endpoint. MoonBack initialization generates the
/// document and registers a GET route serving it as application/json.
pub fn Router::openapi(
  self : Router,
  url : String,
  title~ : String,
  version~ : String,
) -> Unit {
  self.openapi_routes.push({ url, title, version, })
}

///|
fn Route::openapi_operation(
  self : Route,
  ctx : SchemaContext,
  names : Array[String],
  parameter_names : Array[String],
  catch_all : Array[Bool],
) -> Map[String, Json] raise OpenApiError {
  let (request, responses) = if self.schema is Some(schema) {
    schema(ctx)
  } else {
    ({}, { "default": { "description": "Response (schema not provided)" } })
  }
  guard request is Object(fields) && !fields.contains("responses") else {
    raise InvalidSchema(
      "Request schema must be an operation object without responses: \{self.path}",
    )
  }
  let operation = fields.copy()
  let parameters : Array[Json] = []
  let seen : Map[(String, String), Unit] = Map([])
  if operation.get("parameters") is Some(value) {
    guard value is Array(declared) else {
      raise InvalidSchema("parameters must be an array: \{self.path}")
    }
    for parameter in declared {
      guard ctx.resolve(parameter) is Object(fields) &&
        fields.get("name") is Some(String(name)) &&
        fields.get("in") is Some(String(location)) &&
        !name.is_empty() else {
        raise InvalidSchema("Expected a parameter object: \{self.path}")
      }
      let key = (
        location,
        if location == "header" {
          name.to_lower()
        } else {
          name
        },
      )
      guard !seen.contains(key) else {
        raise InvalidSchema("Duplicate parameter: \{location} \{name}")
      }
      seen[key] = ()
      if location == "path" {
        guard names.search(name) is Some(index) else {
          raise InvalidSchema("Unknown path parameter: \{name}")
        }
        guard !(fields.get("required") is Some(False)) else {
          raise InvalidSchema("Path parameter must be required: \{name}")
        }
        let fields = fields.copy()
        fields["name"] = @json.Json::string(parameter_names[index])
        fields["required"] = true
        if catch_all[index] {
          fields["x-moonback-catch-all"] = true
        }
        parameters.push(@json.Json::object(fields))
      } else {
        parameters.push(parameter)
      }
    }
  }
  for index, name in names {
    if seen.contains(("path", name)) {
      continue
    }
    let parameter : Map[String, Json] = {
      "name": @json.Json::string(parameter_names[index]),
      "in": "path",
      "required": true,
      "schema": {},
    }
    if catch_all[index] {
      parameter["x-moonback-catch-all"] = true
    }
    parameters.push(@json.Json::object(parameter))
  }
  if !parameters.is_empty() {
    operation["parameters"] = @json.Json::array(parameters)
  }
  if operation.get("requestBody") is Some(body) && !(body is Object(_)) {
    raise InvalidSchema("requestBody must be an object: \{self.path}")
  }
  operation["responses"] = self.openapi_responses(ctx, responses)
  operation
}

///|
fn Route::openapi_responses(
  self : Route,
  ctx : SchemaContext,
  schema : Json,
) -> Json raise OpenApiError {
  guard schema is Object(declared) && !declared.is_empty() else {
    raise InvalidSchema(
      "Response schema must be a nonempty responses object: \{self.path}",
    )
  }
  let responses : Map[String, Json] = Map([])
  let mut has_response = false
  for status, response in declared {
    if status.has_prefix("x-") {
      responses[status] = response
      continue
    }
    guard status == "default" ||
      status is (['1'..<='5', '0'..<='9', '0'..<='9'] | ['1'..<='5', 'X', 'X']) else {
      raise InvalidSchema("Invalid response status: \{status}")
    }
    guard ctx.resolve(response) is Object(fields) &&
      fields.get("description") is Some(String(_)) else {
      raise InvalidSchema(
        "Expected a response object with a description: \{status}",
      )
    }
    has_response = true
    if self.meth == Head {
      let fields = fields.copy()
      fields.remove("content")
      responses[status] = @json.Json::object(fields)
    } else {
      responses[status] = response
    }
  }
  guard has_response else {
    raise InvalidSchema(
      "Response schema must declare at least one response: \{self.path}",
    )
  }
  @json.Json::object(responses)
}