hs.httpserver.hsminweb

Строка формата, пригодная для os.date, которая отобразит дату в формате, ожидаемом для HTTP-связи, как описано в RFC 822, обновленном RFC 1123.

HTTP-коды состояния ответа

• Ключи и метки в этой таблице были объединены из различных источников, в том числе, но не ограничиваясь:
  • «Официальный» список на https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
  • wsapi от KeplerProject на https://github.com/keplerproject/wsapi
  • Дополнения IIS из https://support.microsoft.com/en-us/kb/943891
• В этой таблице есть дополнения metatable, которые позволяют просмотреть ее содержимое из консоли Hammerspoon, набрав hs.httpserver.hsminweb.statusCodes

Доступно как self._accessLog. Если регистрация запросов включена для веб-сервера, запись журнала Apache common log будет добавляться в эту строку для каждого запроса. См. hs.httpserver.hsminweb:queryLogging.

Доступно как self._errorHandlers[errorCode]. Таблица, ключи которой указывают функцию для генерации страницы ответа об ошибке HTTP.

Доступно как self._serverAdmin. Строка, содержащая администратора веб-сервера. По умолчанию это краткое имя текущего пользователя и локальное имя компьютера, возвращаемое hs.host.localizedName() (например, "user@computer").

Доступно как self._supportMethods[method]. Таблица, ключи которой указывают, поддерживается ли указанный HTTP-метод этим сервером.

Экземпляр hs.logger для модуля hs.httpserver.hsminweb. Дополнительная информация в документации hs.logger.

Возвращает текущее или указанное время в формате, ожидаемом для HTTP-коммуникаций, как описано в RFC 822, обновлённом RFC 1123.

• date - необязательное целое число, задающее дату как количество секунд с 00:00:00 по UTC 1 января 1970. По умолчанию - текущее время, возвращаемое os.time()

• время, указанное как строка в формате, ожидаемом для HTTP-коммуникаций, как описано в RFC 822, обновлённом RFC 1123.

Разбирает указанный URL на составляющие части.

• url - URL для разбора

• таблица, содержащая составляющие части указанного URL. Таблица будет содержать одну или несколько из следующих пар ключ-значение:
  • fragment - имя якоря, на которое ссылается URL в документе HTML. Появляется после '#' в конце URL. Обратите внимание, что не все веб-клиенты включают это в HTTP-запрос, так как его основная цель — указать, куда нужно прокрутить страницу после получения содержимого.
  • host - имя хоста, если есть
  • lastPathComponent - последняя часть пути URL
  • password - пароль, указанный в URL. Обратите внимание, что это не пароль, который вводится при использовании аутентификации Basic или Digest; это пароль, включённый в сам URL. По соображениям безопасности использование этого поля устарело в большинстве ситуаций, и современные браузеры часто запрашивают подтверждение перед передачей URL, содержащих пароль.
  • path - полный путь, указанный в URL
  • pathComponents - массив, содержащий компоненты пути как отдельные строки. Компоненты, которые указывают на подкаталог пути, будут заканчиваться символом "/".
  • pathExtension - если последняя часть пути относится к файлу, расширение файла, если оно есть.
  • port - порт, указанный в URL, если есть
  • query - часть URL после символа «?», если есть; используется для хранения информации запроса, часто из формы, отправляющей свои данные методом GET.
  • resourceSpecifier - часть URL после схемы
  • scheme - схема URL; для веб-трафика это будет "http" или "https"
  • standardizedURL - URL с нормализованными компонентами пути ".." или ".". Использование ".." для ссылки на что-то, предшествующее корню, просто удаляется.
  • URL - URL, как он был предоставлен этой функции (без изменений)
  • user - имя пользователя, указанное в URL. Обратите внимание, что это не имя пользователя, которое вводится при использовании аутентификации Basic или Digest; это имя пользователя, включённое в сам URL. По соображениям безопасности использование этого поля устарело в большинстве ситуаций, и современные браузеры часто запрашивают подтверждение перед передачей URL, содержащих имя пользователя.

• Эта функция отличается от аналогичной функции hs.http.urlParts несколькими способами:
  • Для упрощения логики, используемой этим модулем для определения того, правильно ли запрос каталога завершен символом "/", компоненты пути, возвращаемые этой функцией, не удаляют этот символ из компонента, если он присутствует.
  • Были удалены некоторые лишние или дублирующиеся ключи.
  • Эта функция основана на RFC 3986, в то время как hs.http.urlParts использует функции API OS X, которые основаны на RFC 1808. RFC 3986 устаревает 1808. Основное различие, которое влияет на этот модуль, касается parameters для компонентов пути в URI — RFC 3986 запрещает их в URI, основанных на схеме (например, URL, используемые для веб-трафика).

Создаёт новый объект таблицы hsminweb, представляющий веб-сервер Hammerspoon.

• documentRoot - необязательная строка, определяющая корневой каталог документов для нового веб-сервера. По умолчанию используется подкаталог пользователя Hammerspoon Sites (т.е. os.getenv("HOME").."/Sites").

• таблица, представляющая объект hsminweb.

• корневой каталог веб-сервера — это каталог, содержащий документы или файлы, которые должен обслуживать веб-сервер.
• хотя объект hs.minweb фактически представлен таблицей Lua, ему была назначена метатаблица, которая позволяет вызывать методы непосредственно на нём, как на объекте пользовательских данных. В большинстве случаев следует рассматривать эту таблицу как пользовательские данные модуля.

Получение или установка таблицы списка доступа для веб-сервера hsminweb

• table - необязательная таблица или nil содержащая список доступа для веб-сервера, по умолчанию nil.

• объект hsminwebTable, если параметр указан, или текущее значение, если параметр не указан.

• Функция списка доступа работает, сравнивая заголовки запроса со списком тестов, которые либо принимают, либо отклоняют запрос. Если список доступа не задан (т.е. ему присвоено значение nil), все запросы обслуживаются. Если в этот метод передаётся таблица, все запросы, которые не приняты явно одним из указанных тестов, отклоняются (т.е. в конце списка есть неявное "отклонение").

• Таблица списка доступа — это список тестов, которые оцениваются в порядке. Первый тест, соответствующий данному запросу, определяет, принимается ли запрос или отклоняется.

• Каждый элемент в таблице списка доступа также является таблицей со следующим форматом:

  • { 'header', 'value', isPattern, isAccepted }
    • header - строковое значение, соответствующее имени заголовка. Хотя имя заголовка должно точно совпадать, сравнение выполняется без учёта регистра (т.е. "X-Remote-addr" и "x-remote-addr" будут соответствовать фактическому имени заголовка, которое используется, которое равно "X-Remote-Addr").
    • value - строковое значение, определяющее значение, с которым сравнивается значение ключа заголовка.
    • isPattern - булево значение, указывающее, следует ли сравнивать значение ключа заголовка с value в качестве шаблона совпадения (true) — см. документацию Lua 6.4.1, help.lua._man._6_4_1 в консоли, или как точное совпадение (false)
    • isAccepted - булево значение, указывающее, должно ли совпадение приниматься (true) или отклоняться (false)
  • Особый элемент вида { '*', '*', '*', true } принимает все последующие запросы и может использоваться в качестве последнего элемента, если вы хотите, чтобы список доступа функционировал как список запросов для отклонения, но принимал любые запросы, которые не соответствуют предыдущему тесту.
  • Особый элемент вида { '*', '*', '*', false } отклоняет все последующие запросы и может использоваться в качестве последнего элемента, если вы хотите, чтобы список доступа функционировал как список запросов для принятия, но отклонял любые запросы, которые не соответствуют предыдущему тесту. Это неявный "по умолчанию" конечный тест, если таблица назначена методом accessList и фактически не требует задания, но включён для полноты.
  • Обратите внимание, что любые элементы после элемента, в котором первые два параметра равны '*', никогда фактически не будут использоваться.

• Тесты выполняются в порядке; если вы хотите разрешить один IP-адрес в диапазоне, но отклонить все остальные, вы должны перечислить разрешённые IP-адреса первыми. Например:

  {
     { 'X-Remote-Addr', '192.168.1.100',  false, true },  -- accept requests from 192.168.1.100
     { 'X-Remote-Addr', '^192%.168%.1%.', true,  false }, -- reject all others from the 192.168.1 subnet
     { '*',             '*',              '*',   true }   -- accept all other requests
  }
  

• Большинство доступных заголовков предоставляются запрашивающим веб-браузером, поэтому точный набор доступных заголовков будет разным. Более подробную информацию о распространённых заголовках HTTP-запросов можно найти на сайте https://en.wikipedia.org/wiki/List_of_HTTP_header_fields.

• Следующие заголовки автоматически вставляются hs.httpserver и, вероятно, являются наиболее полезными для использования в списке доступа:

  • X-Remote-Addr - удалённый IPv4 или IPv6-адрес компьютера, отправляющего запрос,
  • X-Remote-Port - TCP-порт удалённого компьютера, откуда произошёл запрос.
  • X-Server-Addr - адрес сервера IPv4 или IPv6, с которого веб-сервер получил запрос. Для компьютеров с несколькими интерфейсами это позволит определить, на каком интерфейсе был получен запрос.
  • X-Server-Port - TCP-порт веб-сервера, который получил запрос.

Получение или установка значения, определяющего, возвращается ли индекс каталога, когда запрашиваемый URL указывает на каталог, а файл, соответствующий элементу в таблице индексов каталогов, не найден.

• flag - необязательный булево значение, по умолчанию false, указывающее, может ли возвращаться индекс каталога, когда не найден файл по умолчанию.

• объект hsminwebTable, если параметр указан, или текущее значение, если параметр не указан.

• если это значение false, попытка извлечения URL, указывающего на каталог, который не содержит файла по умолчанию, как определено одним из элементов списка hs.httpserver.hsminweb:directoryIndex, приведёт к ошибке "403.2".

Получить или установить, следует ли веб-серверу рекламировать себя через Bonjour при запуске.

• flag - необязательный булевый параметр, по умолчанию true, указывающий, следует ли серверу рекламировать себя через Bonjour при запуске.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• Этот флаг может быть изменён только при остановленном сервере (т.е. метод hs.httpserver.hsminweb:start ещё не был вызван, или метод hs.httpserver.hsminweb:stop вызван в первую очередь).

Получить или установить, включена ли обработка CGI-файлов.

• flag - необязательный булевый параметр, по умолчанию false, указывающий, включена ли обработка CGI-скриптов для веб-сервера.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

Получить или установить расширения файлов, которые идентифицируют файлы, которые должны выполняться как CGI-скрипты для предоставления результатов HTTP-запросу.

• table - необязательный параметр типа таблица или nil, по умолчанию { "cgi", "pl" }, задающий список расширений файлов, указывающих, что файл должен выполняться как CGI-скрипт для предоставления содержимого HTTP-запросу.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• Этот список игнорируется, если hs.httpserver.hsminweb:cgiEnabled также не установлен в значение true.

Получить или установить имена файлов для поиска, когда запрашиваемый URL указывает на каталог.

• table - необязательный параметр типа таблица или nil, по умолчанию { "index.html", "index.htm" }, задающий список имён файлов для поиска, когда запрашиваемый URL указывает на каталог. Если файл с одним из имён найден в каталоге, этот файл будет передан вместо каталога.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• Файлы, перечисленные в этой таблице, проверяются в порядке следования, поэтому первый совпавший файл будет передан. Если совпадений нет, сервер вернёт сгенерированный список файлов в каталоге или ошибку "403.2", в зависимости от значения, контролируемого параметром hs.httpserver.hsminweb:allowDirectory.

Получить или установить, выполняются ли запросы DNS.

• flag - необязательный булевый параметр, по умолчанию false, указывающий, выполняются ли запросы DNS.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• DNS-запросы могут быть длительными или даже блокировать Hammerspoon на короткое время, поэтому они отключены по умолчанию.
• В настоящее время DNS-запросы (необязательно) выполняются для CGI-скриптов, но могут быть добавлены для других целей в будущем (логирование и т. п.).

Получить или установить корневой каталог документов для веб-сервера.

• path - необязательный строковый параметр, по умолчанию os.getenv("HOME") .. "/Sites", указывающий, откуда должны предоставляться документы для веб-сервера.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

Получить или установить сетевой интерфейс, на котором будет прослушивать веб-сервер hsminweb.

• interface - необязательный строковый параметр или nil, указывающий сетевой интерфейс, на котором будет прослушивать веб-сервер. Явное nil указывает, что веб-сервер должен прослушивать все активные интерфейсы машины. По умолчанию nil.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• См. hs.httpserver.setInterface для описания допустимых значений, которые могут быть заданы в качестве аргумента interface для этого метода.
• Интерфейс может быть задан только до запуска веб-сервера hsminweb. Если вы хотите изменить интерфейс прослушивания для работающего веб-сервера, вы должны остановить его с помощью hs.httpserver.hsminweb:stop, прежде чем вызывать этот метод, а затем запустить его заново с помощью hs.httpserver.hsminweb:start.

Получить или установить расширение файлов, содержащих Lua-код, который должен выполняться в Hammerspoon для предоставления результатов HTTP-запросу.

• string - необязательная строка или nil, по умолчанию nil, задающая расширение файла, которое указывает, что файл должен выполняться как Lua-код в среде Hammerspoon для предоставления содержимого HTTP-запросу.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• Это расширение проверяется после расширений, заданных для hs.httpserver.hsminweb:cgiExtensions; это означает, что если одно и то же расширение, заданное этим методом, также присутствует в списке CGI-расширений, то файл будет интерпретироваться как CGI-скрипт и игнорировать это значение.

Получить или установить максимальный размер тела для HTTP-запроса.

• size - необязательное целое значение, определяющее максимальный размер тела, разрешённый для входящего HTTP-запроса в байтах. По умолчанию 10485760 (10 МБ).

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• Так как веб-сервер Hammerspoon обрабатывает входящие запросы полностью в памяти, этот метод устанавливает ограничение на максимальный размер запроса POST или PUT.
• Если размер тела запроса превышает это значение, hs.httpserver вернёт код состояния 405 для метода, прежде чем этот модуль получит запрос.

Получение или установка имени, используемого веб-сервером в рекламе Bonjour при работе веб-сервера.

• name - необязательная строка, определяющая имя, под которым сервер рекламирует себя при включенном Bonjour и работе веб-сервера. По умолчанию nil, что приводит к рекламе сервера с именем компьютера, определенным в панели «Параметры совместного доступа» для компьютера.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

Установка пароля для веб-сервера hsminweb или возврат булевого значения, указывающего, установлен ли пароль для веб-сервера.

• password - необязательная строка, содержащая пароль сервера, или явное nil для удаления существующего пароля.

• объект hsminwebTable, если параметр предоставлен, или булевое значение, указывающее, установлен ли пароль, если параметр не указан.

• пароль, если он установлен, действует для всего сервера и заставляет сервер использовать схему аутентификации Basic со строкой пустым значением для имени пользователя.
• данный модуль является расширением основного модуля Hammerspoon hs.httpserver, поэтому он имеет те же ограничения относительно паролей сервера. См. документацию для hs.httpserver.setPassword (help.hs.httpserver.setPassword в консоли Hammerspoon).

Получение или установка номера порта, на котором прослушивает веб-сервер

• port - необязательное целое число, определяющее TCP-порт, на котором сервер прослушивает запросы во время работы. По умолчанию nil, что заставляет сервер случайным образом выбирать порт при запуске.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• из-за ограничений безопасности, наложенных OS X, порт должен быть числом больше 1023

Получение или установка значения, определяющего, производятся ли логи запросов на этот веб-сервер.

• flag - необязательный булев параметр, по умолчанию false, указывающий, производятся ли логи запросов.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• Если ведение журнала включено, запись журнала в стиле Apache common добавляется в self._accesslog для каждого запроса к веб-серверу.
• Сообщения об ошибках при генерации содержимого всегда записываются в консоль Hammerspoon с помощью экземпляра hs.logger, сохраненного в hs.httpserver.hsminweb.log.

Получение или установка таймаута для CGI-скрипта

• целое число - необязательное целое число, по умолчанию 30, определяющее время в секундах, в течение которого CGI-скрипту разрешено работать, прежде чем он будет принудительно завершен, если он еще не выполнил свою задачу.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• С текущей функциональностью, доступной в hs.httpserver, любой скрипт, который ожидается вернуть содержимое для HTTP-запроса, должен работать в режиме блокировки — это означает, что никакая другая активность Hammerspoon не может происходить во время выполнения скрипта. Этот параметр позволяет задать максимальное время, в течение которого такой скрипт может приостанавливать работу, прежде чем быть прерванным.
• Рассматривается альтернативная реализация по крайней мере некоторых методов, доступных в hs.httpserver, что может сделать возможным использование hs.task для этих скриптов, что устранит это блокирующее поведение. Однако даже если это будет решено, таймаут для скриптов все же желателен, чтобы клиент, отправляющий запрос, не ждал вечно, если скрипт некорректен.

Получение или установка значения, определяющего, использует ли веб-сервер SSL для связи HTTP-запросов и ответов.

• flag - необязательный булев параметр, по умолчанию false, указывающий, использует ли сервер SSL для HTTP-трафика запросов и ответов.

• объект hsminwebTable, если параметр предоставлен, или текущее значение, если параметр не указан.

• этот флаг может быть изменён только когда сервер не запущен (т.е. метод hs.httpserver.hsminweb:start ещё не был вызван или метод hs.httpserver.hsminweb:stop вызван первым).
• данный модуль является расширением основного модуля Hammerspoon hs.httpserver, поэтому он имеет те же соображения относительно SSL. См. документацию для hs.httpserver.new (help.hs.httpserver.new в консоли Hammerspoon).

Начать предоставление страниц для веб-сервера hsminweb.

• Нет

• объект hsminWebTable

Остановить предоставление страниц для веб-сервера hsminweb.

• Нет

• объект hsminWebTable

• Этот метод вызывается автоматически при сборе мусора.