Internet Engineering Task Force (IETF) M. Bettini
Request for Comments: 9585 Open-Xchange Oy
Category: Standards Track May 2024
ISSN: 2070-1721
This document defines a new IMAP untagged response code, "INPROGRESS", that provides progress notifications regarding the status of long-running commands.
このドキュメントでは、長期にわたるコマンドのステータスに関する進捗通知を提供する新しいIMAP未編成の応答コード「InProgress」を定義します。
This is an Internet Standards Track document.
これは、インターネット標準トラックドキュメントです。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
このドキュメントは、インターネットエンジニアリングタスクフォース（IETF）の製品です。IETFコミュニティのコンセンサスを表しています。公開レビューを受けており、インターネットエンジニアリングステアリンググループ（IESG）からの出版が承認されています。インターネット標準の詳細については、RFC 7841のセクション2で入手できます。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9585.
このドキュメントの現在のステータス、任意のERRATA、およびそのフィードバックを提供する方法に関する情報は、https://www.rfc-editor.org/info/rfc9585で取得できます。
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.
著作権（c）2024 IETF Trustおよび文書著者として特定された人。無断転載を禁じます。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.
このドキュメントは、BCP 78およびIETFドキュメント（https://trustee.ietf.org/license-info）に関連するIETF Trustの法的規定の対象となります。この文書に関するあなたの権利と制限を説明するので、これらの文書を注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、セクション4.Eで説明されている法的規定のセクション4.Eで説明されており、改訂されたBSDライセンスで説明されている保証なしで提供されるように、改訂されたBSDライセンステキストを含める必要があります。
1. Introduction
2. Conventions Used in This Document
3. CAPABILITY Identification
4. The "INPROGRESS" Response Code
5. Formal Syntax
6. Security Considerations
7. IANA Considerations
8. Normative References
Author's Address
IMAP commands [RFC9051] can require a considerable amount of time to be completed by the server. In these cases, the client has no information about the progress of the commands. It is already possible to expose updates with a generic untagged response, like "* OK Still on it, 57% done"; however, this does not provide a standard way to communicate with the client and does not allow the server to inform the client of the progress of the long-running actions.
IMAPコマンド[RFC9051]には、サーバーが完了するにはかなりの時間がかかる場合があります。これらの場合、クライアントはコマンドの進捗に関する情報を持っていません。「* OKまだ、57％が完了しました」など、一般的な未編成の応答で更新を公開することはすでに可能です。ただし、これはクライアントと通信する標準的な方法を提供するものではなく、サーバーがクライアントに長期にわたるアクションの進捗状況を通知することを許可しません。
This document extends the Internet Message Access Protocol (IMAP) [RFC9051] with:
このドキュメントは、インターネットメッセージアクセスプロトコル（IMAP）[RFC9051]を次のように拡張します。
* a new "INPROGRESS" response code [RFC5530]. The new response code provides a consistent means for a client to receive progress notifications on command completion status.
* 新しい「プログレス」応答コード[RFC5530]。新しい応答コードは、クライアントがコマンド完了ステータスに関する進行状況通知を受信するための一貫した手段を提供します。
* a new "INPROGRESS" capability [RFC9051]. The new capability informs the client that the server emits progress notifications via the "INPROGRESS" response code.
* 新しい「プログレス」機能[RFC9051]。新しい機能は、サーバーが「InProgress」応答コードを介して進行状況通知を発することをクライアントに通知します。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
キーワード「必須」、「必要」、「必須」、「shall」、「shall」、「shill "of"、 "nove"、 "becommended"、 "becommented"、 "may"、 "optional「このドキュメントでは、BCP 14 [RFC2119] [RFC8174]で説明されているように解釈されます。
The word "can" (not "may") is used to refer to a possible circumstance or situation, as opposed to an optional facility of the protocol.
「can」（「not 'not」）という言葉は、プロトコルのオプションの施設とは対照的に、考えられる状況または状況を指すために使用されます。
Conventions for notations are as in [RFC9051] and [RFC5530].
表記の規則は、[RFC9051]および[RFC5530]と同様です。
In examples, "C:" and "S:" indicate lines sent by the client and server, respectively. Note that each line includes the terminating CRLF.
例では、「C：」と「S：」は、それぞれクライアントとサーバーから送信された行を示します。各ラインには終了CRLFが含まれていることに注意してください。
IMAP servers that support this extension MUST include "INPROGRESS" in the response list to the CAPABILITY command.
この拡張機能をサポートするIMAPサーバーは、機能コマンドへの応答リストに「InProgress」を含める必要があります。
The server MAY send the "INPROGRESS" response code to notify the client about the progress of the commands in execution or simply to prevent the client from timing out and terminating the connection. The notifications MAY be sent for any IMAP command. If the server elects to send notifications, it is RECOMMENDED that these are sent every 10-15 seconds.
サーバーは、「InProgress」応答コードを送信して、実行中のコマンドの進捗状況についてクライアントに通知するか、単にクライアントが接続のタイミングを出して終了しないようにすることができます。通知は、IMAPコマンドに対して送信される場合があります。サーバーが通知を送信することを選択した場合、これらは10〜15秒ごとに送信することをお勧めします。
The response code is meant to appear embedded inside an untagged OK reply. The response code MUST NOT appear in a tagged response (the command has completed and further progress notifications make no sense).
応答コードは、未編成のOK応答の内部に埋め込まれているように見えることを目的としています。応答コードはタグ付き応答に表示されてはなりません（コマンドは完了し、さらに進行通知が意味がありません）。
The response code MAY embed a list of details, which appear in the following order:
応答コードには、次の順序で表示される詳細のリストが埋め込まれている場合があります。
1. CMD-TAG: the tag [RFC9051] that originated the long-running command. If the tag is not available or if it contains the "]" character, it MUST be set to NIL. This still produces a usable notification, unless multiple commands are in flight simultaneously. A client can ensure reception of notifications with tags by simply refraining from the use of the character "]" in the originating command tags.
1. CMD-TAG：長期にわたるコマンドを発信したタグ[RFC9051]。タグが使用できない場合、または「]」文字が含まれている場合は、nilに設定する必要があります。複数のコマンドが同時に飛行中でない限り、これにより使用可能な通知が生成されます。クライアントは、元のコマンドタグで文字「]」の使用を控えるだけで、タグで通知を受信することを保証できます。
2. PROGRESS: a number indicating the number of items processed so far. The number MUST be non-negative and SHOULD be monotonically increasing. If the PROGRESS is not available, both PROGRESS and GOAL MUST be set to NIL.
2. 進捗状況：これまでに処理されたアイテムの数を示す数。数は非陰性でなければならず、単調に増加する必要があります。進捗状況が利用できない場合、進捗と目標の両方をゼロに設定する必要があります。
3. GOAL: a number indicating the total number of items to be processed. The number MUST be positive, and it SHOULD NOT change between successive notifications for the same command tag. This is the number that PROGRESS is expected to reach after the completion of the command; therefore, it MUST be greater than PROGRESS. If the GOAL is not known, it MUST be set to NIL.
3. 目標：処理するアイテムの総数を示す数。数値はプラスである必要があり、同じコマンドタグの連続した通知間で変更しないでください。これは、コマンドが完了した後に進行すると予想される数です。したがって、それは進歩よりも大きくなければなりません。目標がわからない場合は、ゼロに設定する必要があります。
If the response code does not embed a list of details, all details are to be interpreted as NIL.
応答コードに詳細のリストが埋め込まれていない場合、すべての詳細はnilと解釈されます。
The server can provide the progress details with different degrees of completeness:
サーバーは、異なる程度の完全性で進行状況の詳細を提供できます。
- bare keepalive
* OK [INPROGRESS] Hang in there...
- keepalive with an indication of the command tag
* OK [INPROGRESS ("tag" NIL NIL)] Hang in there...
- progress notification with unknown GOAL
* OK [INPROGRESS ("tag" 175 NIL)] Processed 175 items so far
- progress notification with an indication of the GOAL
* OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items
Examples:
例：
C: A001 search text "this will be slow"
[13 seconds later]
S: * OK [INPROGRESS ("A001" 454 1000)] Processed 45% of the items
[14 seconds later]
S: * OK [INPROGRESS ("A001" 999 1000)] Processed 99% of the items
[5 seconds later]
S: * SEARCH 447 735
S: A001 OK Search completed (23.387 + 0.004 + 0.017 secs).
C: A003 COPY 2000:4000 Meeting-Minutes
[12 seconds later]
S: * OK [INPROGRESS ("A003" 175 2001)] Still working on this...
[14 seconds later]
S: * OK [INPROGRESS ("A003" 440 2001)] Still working on this...
[13 seconds later]
S: * OK [INPROGRESS ("A003" 987 2001)] Still working on this...
[14 seconds later]
S: * OK [INPROGRESS ("A003" 1388 2001)] Still working on this...
[14 seconds later]
S: * OK [INPROGRESS ("A003" 1876 2001)] Still working on this...
[9 seconds later]
S: A003 OK Copy completed
PROGRESS and GOAL SHOULD be counts of the kind of item being processed -- in most cases, messages counts. If that is not possible, the counts SHOULD be percentages, with GOAL set to 100 and PROGRESS varying between 0 and 99.
進捗と目標は、処理されるアイテムの種類のカウントである必要があります。ほとんどの場合、メッセージはカウントされます。それが不可能な場合、カウントはパーセンテージでなければなりません。目標は100に設定され、進行状況は0〜99の間で変化します。
The server SHOULD NOT send a progress notification where PROGRESS equals GOAL, as that would mean the command is completed. In that case, the proper tagged response should be emitted instead.
サーバーは、コマンドが完了することを意味するため、進行状況が目標に等しい場合の進行状況通知を送信してはなりません。その場合、代わりに適切なタグ付き応答を放出する必要があります。
If the command completes before the first server notification deadline, there will be no notifications at all. The client MUST assume PROGRESS to be 0 and GOAL to be unknown until the server issues a notification for the command.
最初のサーバー通知の締め切りの前にコマンドが完了した場合、通知はまったくありません。クライアントは、サーバーがコマンドの通知を発行するまで、進行状況が0であり、目標が不明であると想定する必要があります。
While the server SHOULD keep GOAL constant and PROGRESS monotonically increasing, there are circumstances where this might not be possible. The client MUST be prepared to handle cases where the server cannot keep GOAL constant and/or PROGRESS monotonically increasing. When the GOAL changes or the PROGRESS goes backward, the RECOMMENDED interpretation is that the previous GOAL has been reached, but the server discovered that further (long-running) work is required (with a new known or unknown GOAL).
サーバーは目標を一定に保ち、単調に進行する必要がありますが、これが不可能な状況があります。クライアントは、サーバーが目標を一定に保つことができない場合や単調に進行することができないケースを処理するために準備する必要があります。目標が変化するか、進捗が後退すると、推奨される解釈は、以前の目標に達したことですが、サーバーは、さらに（長期間の）作業が必要であることを発見しました（新しい既知または未知の目標を使用）。
The client MAY disregard progress notifications entirely or process them only in relation to specific commands. If a user interface is involved, it is the client's duty to decide which of these notifications should emerge to the user interface and/or modify the user's ability to interact in their presence, since this may differ based on implementation details.
クライアントは、進行状況通知を完全に無視するか、特定のコマンドに関連してのみ処理する場合があります。ユーザーインターフェイスが関与している場合、これらの通知のどれがユーザーインターフェイスに出現するかを決定したり、ユーザーの存在下で対話する能力を変更することはクライアントの義務です。
Also, the client MUST NOT consider the values to be authoritative for any other use than evaluating the progress of the commands. For example, the client must not use the GOAL field in place of the proper output of a SEARCH command to know the number of messages in a folder.
また、クライアントは、コマンドの進捗を評価する以外の使用に対して、値を他の使用に対して信頼できると考えるべきではありません。たとえば、クライアントは、検索コマンドの適切な出力の代わりにゴールフィールドを使用して、フォルダー内のメッセージの数を知る必要があります。
The following syntax specification uses the Augmented Backus-Naur Form (ABNF) [RFC5234] notation. Elements not defined here can be found in the formal syntax of the ABNF [RFC5234] and IMAP [RFC9051] specifications.
次の構文仕様では、拡張されたBackus-Naurフォーム（ABNF）[RFC5234]表記を使用します。ここで定義されていない要素は、ABNF [RFC5234]およびIMAP [RFC9051]仕様の正式な構文にあります。
Except as noted otherwise, all alphabetic characters are case-insensitive. The use of uppercase or lowercase characters to define token strings are for editorial clarity only. Implementations MUST accept these strings in a case-insensitive fashion.
それ以外の場合は、言及されている場合を除き、すべてのアルファベット文字はケース非感受性です。トークン文字列を定義するために大文字または小文字の文字を使用することは、編集の明確さのみです。実装は、これらの文字列をケースに依存しない方法で受け入れる必要があります。
inprogress-tag = quoted / nil
inprogress-state-unknown = nil SP nil
inprogress-state-counting = number SP nil
inprogress-state-known-goal = number SP nz-number
inprogress-state = inprogress-state-unknown
/ inprogress-state-counting
/ inprogress-state-known-goal
resp-text-code =/ "INPROGRESS" [ SP "(" inprogress-tag SP
inprogress-state ")" ]
The details of the response code are not expected to disclose any information that isn't currently available from the command output. The progress details could be obtained anyway by sending a series of commands with different workloads -- by either constructing data sets or searching in the appropriate way.
応答コードの詳細は、コマンド出力から現在利用できない情報を開示するとは期待されていません。進行状況の詳細は、データセットを構築するか、適切な方法で検索することにより、さまざまなワークロードで一連のコマンドを送信することにより、とにかく取得できます。
The client must protect itself against data sent by a malicious server. Specifically, the client should guard against values that can cause arithmetic exceptions, like GOAL = 0, GOAL/VALUE < 0, GOAL/ VALUE ≥ 2^32 (these are not possible within a correct implementation of the ABNF syntax above), and VALUE > GOAL. In these cases, the notification MUST be disregarded.
クライアントは、悪意のあるサーバーから送信されたデータから自分自身を保護する必要があります。具体的には、クライアントは、目標= 0、目標/値<0、目標/値≥2^32などの算術例外を引き起こす可能性のある値から守る必要があります（上記のABNF構文の正しい実装内でこれらは不可能です）、値>目標。これらの場合、通知は無視する必要があります。
IANA has added "INPROGRESS" to the "IMAP Response Codes" registry located at <https://www.iana.org/assignments/imap-response-codes>, with a reference to this document.
IANAは、このドキュメントを参照して、<https://www.iana.org/assignments/imap-response-codes>にある「IMAP応答コード」レジストリに「Inprogress」を追加しました。
IANA had added "INPROGRESS" to the "IMAP Capabilities" registry located at <https://www.iana.org/assignments/imap-capabilities>, with a reference to this document.
IANAは、このドキュメントを参照して、<https://www.iana.org/assignments/imap-capability>にある「IMAP機能」レジストリに「Inprogress」を追加しました。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[RFC5530] Gulbrandsen, A., "IMAP Response Codes", RFC 5530,
DOI 10.17487/RFC5530, May 2009,
<https://www.rfc-editor.org/info/rfc5530>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
Access Protocol (IMAP) - Version 4rev2", RFC 9051,
DOI 10.17487/RFC9051, August 2021,
<https://www.rfc-editor.org/info/rfc9051>.
Marco Bettini
Open-Xchange Oy
Lars Sonckin kaari 10
FI-02600 Espoo
Finland
Email: marco.bettini@open-xchange.com