Biomaj-download

关于

管理biomaj下载的微服务。

在 biomaj_download/message/downmessage_pb2.py 中提供了一个 protobuf 接口，用于 BioMAJ 与下载服务之间交换消息。消息通过 RabbitMQ（需要安装）进行传输。

仅支持 Python3，已停止对 Python2 的支持

Protobuf

如果您对 protobuf 代码进行了修改，则需要将其编译成 Python 代码

cd /tmp/protoc/
PB_REL="https://github.com/protocolbuffers/protobuf/releases"
curl -LO $PB_REL/download/v23.2/protoc-23.2-linux-x86_64.zip  # Version used by GitHub Actions currently
unzip protoc-23.2-linux-x86_64.zip
cd ..../biomaj_download/message/
/tmp/protoc/bin/protoc --python_out=. downmessage.proto

开发

测试

要运行测试套件，请使用

LOCAL_IRODS=0 pytest -v tests/biomaj_tests.py

此命令会跳过需要本地 iRODS 服务器的测试

由于网络连接问题，某些测试可能会失败。您可以使用以下命令跳过它们

NETWORK=0 pytest -v tests/biomaj_tests.py

运行

消息消费者

export BIOMAJ_CONFIG=path_to_config.yml
python bin/biomaj_download_consumer.py

Web 服务器

如果通过 pip 安装了包，您需要在本地服务器上的某个位置有一个名为 gunicorn_conf.py 的文件

def worker_exit(server, worker):
    from prometheus_client import multiprocess
    multiprocess.mark_process_dead(worker.pid)

如果您已克隆了存储库并使用 python setup.py install 进行安装，请参阅克隆存储库中的 gunicorn_conf.py

export BIOMAJ_CONFIG=path_to_config.yml
rm -rf ..path_to/prometheus-multiproc
mkdir -p ..path_to/prometheus-multiproc
export prometheus_multiproc_dir=..path_to/prometheus-multiproc
gunicorn -c gunicorn_conf.py biomaj_download.biomaj_download_web:app

Web 进程应该在代理/负载均衡器后面，API 基础 URL 为 /api/download

Prometheus 端点指标通过 Web 服务器上的 /metrics 进行暴露

重试

下载大量文件时，常见的难题是处理临时故障（网络问题、服务器过于繁忙无法响应等）。从版本 3.1.2 开始，biomaj-download 使用了 Tenacity 库，该库专门设计用来处理这些问题。此机制可以通过 2 个特定于下载器的选项进行配置（参见 下载选项）：stop_condition 和 wait_policy。

在处理 Python 代码时，您可以传递 Tenacity 的 stop_base 和 wait_base 实例。这包括 Tenacity 中定义的类或您自己的派生类。

对于银行配置，这些选项也会解析配置文件中读取的字符串。此解析基于 Simple Eval 库。规则很简单

• 在 Tenacity 中定义的所有具体的停止和等待类（即分别继承自 stop_base 和 wait_base 的类）都可以通过调用其构造函数并传入预期参数来使用。例如，字符串 "stop_after_attempt(5)" 将创建所需的对象。请注意，不需要参数的停止和等待类必须用作常量（即使用 "stop_never" 而不是 "stop_never()"）。目前，这适用于 "stop_never"（如在 Tenacity 中）和 "wait_none"（这与 Tenacity 中略有不同，它是 "wait_none()"）。
• 您可以使用允许组合其他停止条件（即 stop_all 和 stop_any）或等待策略（即 wait_combine）的类。
• 可以使用操作符 + 来添加等待策略（类似于 wait_combine）。
• 可以使用操作符 & 和 | 来组合停止条件（类似于 wait_all 和 wait_none 分别）。

但是，在这种情况下，您不能使用自己的条件。停止条件的完整列表如下

• stop_never（尽管不建议使用）
• stop_after_attempt
• stop_after_delay
• stop_when_event_set
• stop_all
• stop_any

等待策略的完整列表如下

• wait_none
• wait_fixed
• wait_random
• wait_incrementing
• wait_exponential
• wait_random_exponential
• wait_combine
• wait_chain

请参阅 Tenacity 文档 了解它们的含义和参数。

示例（受 Tenacity 文档启发）

• "wait_fixed(3) + wait_random(0, 2)" 和 "wait_combine(wait_fixed(3), wait_random(0, 2))" 是等效的，并将等待 3 秒 + 最多 2 秒的随机延迟
• "wait_chain(*([wait_fixed(3) for i in range(3)] + [wait_fixed(7) for i in range(2)] + [wait_fixed(9)]))" 将等待 3s 进行 3 次尝试，7s 进行下一次 2 次尝试，之后的所有尝试将等待 9s（这里 + 是列表连接）。
• "wait_none + wait_random(1,2)" 将在 1 秒和 2 秒之间等待（因为 wait_none 不会等待）。
• "stop_never | stop_after_attempt(5)" 将在 5 次尝试后停止（因为 stop_never 永不停止）。

请注意，一些协议（例如 FTP）将错误分类为临时或永久（例如尝试下载不存在的文件）。更普遍地说，我们可以根据错误代码等区分永久性错误，并在这种情况下不重试。然而，根据我们的经验，所谓的永久性错误可能只是暂时的。因此，下载器在遇到任何错误时都会重试。在某些情况下，这会浪费时间，但通常这是值得的。

主机密钥

当使用 sftp 协议时，biomaj-download 必须检查主机密钥。这些密钥存储在文件中（例如 ~/.ssh/known_hosts）。

有几种选项可以配置此功能

• ssh_hosts_file 设置要使用的文件
• ssh_new_host 设置对新主机的操作

当在文件中找到主机和密钥时，连接将被接受。如果找到主机但密钥不匹配，则连接将被拒绝（这通常表示远程服务器存在问题或配置更改）。当未找到主机时，决定取决于 ssh_new_host 的值

• reject 表示拒绝连接
• accept 表示接受连接
• add 表示接受连接并将密钥添加到文件中

请参阅下载选项中的选项描述。

下载选项

从版本 3.0.26 开始，您可以使用 set_options 方法传递一个字典，其中包含下载器特定的选项。以下列表显示了一些选项及其效果（要设置的选项是键，参数是关联的值）

• stop_condition:
  • 参数：Tenacity stop_base 的实例或字符串（见重试）。
  • 下载器：所有（除了 LocalDownload）。
  • 效果：设置我们应停止重试下载文件的条件。
  • 默认值：stop_after_attempt(3)（即尝试 3 次后停止）。
  • 注意：从版本 3.2.1 中引入。
• wait_policy:
  • 参数：Tenacity wait_base 的实例或字符串（见重试）。
  • 下载器：所有（除了 LocalDownload）。
  • 效果：设置下载尝试之间的等待策略。
  • 默认值：wait_fixed(3)（即在尝试之间等待 3 秒）。
  • 注意：从版本 3.2.1 中引入。
• skip_check_uncompress:
  • 参数：布尔值。
  • 下载器：所有（除了 LocalDownload）。
  • 效果：如果为 true，则下载后不测试存档。
  • 默认值：false（即测试存档）。
• ssl_verifyhost:
  • 参数：布尔值。
  • 下载器：CurlDownload（及其派生类：DirectFTPDownload、DirectHTTPDownload）。
  • 效果：如果为 false，则不检查远程服务器名称是否与 SSL 证书中的名称相同。
  • 默认值：true（即检查主机名）。
  • 注意：通常不建议禁用此验证。但是，某些服务器配置不当。请参阅此处了解相应的 cURL 选项。
• ssl_verifypeer:
  • 参数：布尔值。
  • 下载器：CurlDownload（及其派生类：DirectFTPDownload、DirectHTTPDownload）。
  • 效果：如果为 false，则不检查对等证书的真实性。
  • 默认值：true（即检查真实性）。
  • 注意：通常不建议禁用此验证。但是，某些服务器配置不当。请参阅此处了解相应的 cURL 选项。
• ssl_server_cert:
  • 参数：证书文件的路径。
  • 下载器：CurlDownload（及其派生类：DirectFTPDownload、DirectHTTPDownload）。
  • 效果：使用此文件中的证书验证对等方。
  • 默认值：使用操作系统证书。
  • 注意：请参阅此处了解相应的 cURL 选项。
  • 参数：整数。
  • 下载器：CurlDownload（及其派生类：DirectFTPDownload、DirectHTTPDownload）。
  • 效果：设置操作系统在发送 keepalive 探针之间的等待间隔（以秒为单位）。
  • 默认值：cURL 默认值（本文撰写时的 60 秒）。
  • 注意：请参阅此处了解相应的 cURL 选项。
• ftp_method:
  • 参数：以下之一 default、multicwd、nocwd、singlecwd（不区分大小写）。
  • 下载器：CurlDownload（及其派生类：DirectFTPDownload、DirectHTTPDownload）- 仅用于 FTP(S)。
  • 效果：设置访问 FTP(S) 服务器上文件的策略（nocwd 和 singlecwd 通常更快，但并不总是受支持）。
  • 默认值：default（在撰写本文时为 multicwd，如 cURL）。
  • 注意：请参阅此处了解相应的 cURL 选项；自版本 3.1.2 以来引入。
• ssh_hosts_file:
  • 参数：已知主机文件路径。
  • 下载器：CurlDownload（及其派生类：DirectFTPDownload、DirectHTTPDownload）- 仅用于 SFTP。
  • 效果：设置用于读取/存储 SFTP 主机密钥的文件。
  • 默认值：~/.ssh/known_hosts（其中 ~ 是当前用户的家目录）。
  • 注意：请参阅此处了解相应的 cURL 选项和下面的选项；自版本 3.2.1 以来引入。
• ssh_new_host:
  • 参数：以下之一 reject、accept、add。
  • 下载器：CurlDownload（及其派生类：DirectFTPDownload、DirectHTTPDownload）- 仅用于 SFTP。
  • 效果：设置用于未知主机的策略。
  • 默认值：reject（即拒绝新主机 - 您必须将其添加到文件中，例如使用 ssh 或 sftp）。
  • 注意：请参阅此处了解相应的 cURL 选项和上面的选项；自版本 3.2.1 以来引入。
• allow_redirections:
  • 参数：布尔值。
  • 下载器：CurlDownload（及其派生类：DirectFTPDownload、DirectHTTPDownload）- 仅用于 HTTPS(S)。
  • 效果：设置 HTTP 重定向的策略。
  • 默认值：true（即遵循重定向）。
  • 注意：请参阅此处了解相应的 cURL 选项；自版本 3.2.3 以来引入。

这些选项可以在银行属性中设置。请参阅biomaj 模块中的文件 global.properties.example。

3.2.12：按正确的字母顺序排序下载。

3.2.11：修复插件使用情况下的直接处理程序。

3.2.10：重新生成 proto 消息。

3.2.9：将 nose 替换为 pytest 进行单元测试。

3.2.8：接受 ftp 的 257 错误代码。

3.2.7：使用其他 biomaj 组件标准化 pyyaml 设置。

3.2.6：禁用 tenacity 测试，从库中删除 compat.make_retry_state。

3.2.5：修复 */ 的正则表达式处理。

3.2.4：#39 directhttp 下载问题 biomaj 发送文件名而不是文件字典，解决此 #28 CurlDownload 在 cURL 不支持 SFTP 时崩溃的问题。Python 文档和错误消息更新。抑制 yaml 警告。

3.2.3：#30：在 list() 失败时引发错误 DirectHTTP(s)/DirectFTP(s)：在步骤列表中不引发错误，因为 HEAD 可能不受支持 #35：允许重定向（关闭 #33）

3.2.2：#31 修复包含多个斜杠的 URL。更新演示密码以进行 ftps 网站测试。移除对 python2 的支持。

3.2.1：#26 接受 SFTP 服务器的新密钥（关闭 #25）移除远程文件列表中的额外斜杠字符（由于正则表达式解析） #20 添加一个可配置的机制，当下载失败时重试下载 #24 加快 IRODDownload 速度。在执行网络方法之前执行配置的方法。调整通用方法和子类实现。解决解析器在只想列出文件时分析日消息的问题。（#23）

3.1.2：#18 添加协议选项以设置 CURLOPT_FTP_FILEMETHOD #19 将协议选项重命名为选项。修复当文件位于子目录中时复制生产文件而不是下载的问题。

3.1.1：#17 支持直接 ftp 中的 MDTM 命令。

3.1.0：#16 在 DirectHTTPDownloader 下载后不更改名称 PR #7。重构下载器（警告：破坏 API）

3.0.27: 修复先前版本中直接协议的bug导致的损坏

3.0.26: 将默认下载超时时间更改为1小时 #12 允许FTPS协议 #14 添加针对特定协议的选项机制

3.0.25: 允许在LocalDownload中使用硬链接

3.0.24: 移除调试日志

3.0.23: 支持远程文件名中的空格

3.0.22: 修复 */ remote.files 解析

3.0.21: 修复traefik标签

3.0.20: 更新pika依赖版本，为traefik添加标签

3.0.19: 下载后检查归档，修复python正则表达式语法（弃用）

3.0.18: 重命名protobuf并使用特定包以避免冲突

3.0.17: 重新生成protobuf消息描述，在python3上失败

3.0.16: 在setup.py中添加缺少的req

3.0.15: 修复可能导致无限循环的进度下载控制，添加irods下载

3.0.14: 允许为每个服务设置local_endpoint，否则使用默认的local_endpoint

3.0.13: 在速率限制中，添加下载进度与总下载量的比较，修复速率限制提交

3.0.12: 在会话创建失败的情况下添加重试，禁用web线程日志

3.0.11: 通过下载百分比显示下载进度，在下载client中发生联系错误时重试连接

3.0.10: 功能 #3：添加速率限制选项以限制客户端的并行下载数量

3.0.9: 在prometheus统计中添加主机，修复 #2：如果http(s)页面中不可用，则允许设置http.group.file.size或http.group.file.date为-1

3.0.8: 修复prometheus统计，添加consul监督

3.0.7: 将大小类型更改为int64

3.0.6: 修复download_or_copy以避免在先前的生产目录中下载已存在的文件

3.0.4: 消息修复

3.0.3: 修复使用biomaj.download参数时导致崩溃的超时管理

3.0.2: 将rabbitmq参数设置为可选

3.0.1: 在包中添加缺少的README等文件

3.0.0: 将下载管理从biomaj主包中移出