fix(backend): 虚無ノートを投稿できる問題の修正と api.json の OpenAPI Specification 3.1.0 への対応

[zyoshoka]

What

• notes/create に対して投げるリクエストの text が null または空白文字のみで構成されていて、かつそのリクエストが text のみの場合、INVALID_PARAM を返すようにしました。
• notes/create に対して投げるリクエストがリノート、ファイルまたは投票を含んでいて、かつ text が空白文字のみで構成されている場合、レスポンスの text を "" から null になるように変更しました。
• JSON Schema で If-Then-Else を使いたかったので OpenAPI Specification を 3.1.0 に上げました。本 PR ではそれに伴う変更が含まれています。

Why

Fix: #12381

Additional info (optional)

以下のテストを追加しています。

• text が null または空白文字のみで構成されていて、かつリクエストが text のみの場合、Ajv 側で invalid になる
• notes/create に対して text が空白文字のみで構成された引用renoteを投げたとき、レスポンスの text が null になる

Checklist

• Read the contribution guide
• Test working in a local environment
• (If needed) Add story of storybook
• (If needed) Update CHANGELOG.md
• (If possible) Add tests

[github-actions]

このPRによるapi.jsonの差分

差分はこちら

--- base
+++ head
@@ -1,5 +1,5 @@
 {
-  "openapi": "3.0.0",
+  "openapi": "3.1.0",
   "info": {
     "version": "2023.12.2",
     "title": "Misskey API",
@@ -51699,33 +51699,36 @@
                     ]
                   }
                 },
-                "anyOf": [
-                  {
-                    "required": [
-                      "text"
-                    ]
-                  },
-                  {
-                    "required": [
-                      "renoteId"
-                    ]
-                  },
-                  {
-                    "required": [
-                      "fileIds"
-                    ]
-                  },
-                  {
-                    "required": [
-                      "mediaIds"
-                    ]
-                  },
-                  {
-                    "required": [
-                      "poll"
-                    ]
+                "if": {
+                  "properties": {
+                    "renoteId": {
+                      "type": "null"
+                    },
+                    "fileIds": {
+                      "type": "null"
+                    },
+                    "mediaIds": {
+                      "type": "null"
+                    },
+                    "poll": {
+                      "type": "null"
+                    }
                   }
-                ]
+                },
+                "then": {
+                  "properties": {
+                    "text": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 3000,
+                      "nullable": false,
+                      "pattern": "[^\\s]+"
+                    }
+                  },
+                  "required": [
+                    "text"
+                  ]
+                }
               }
             }
           }

Get diff files from Workflow Page

[codecov]

Codecov Report

Attention: 9 lines in your changes are missing coverage. Please review.

Comparison is base (6177fcb) 76.81% compared to head (cb224e6) 65.59%.
Report is 2 commits behind head on develop.

Files	Patch %	Lines
...ackages/backend/src/server/api/openapi/gen-spec.ts	0.00%	6 Missing ⚠️
packages/backend/src/core/NoteCreateService.ts	33.33%	2 Missing ⚠️
packages/backend/src/server/api/openapi/schemas.ts	95.83%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           develop   #12969       +/-   ##
============================================
- Coverage    76.81%   65.59%   -11.23%     
============================================
  Files          175      961      +786     
  Lines        22794   109500    +86706     
  Branches       430     5526     +5096     
============================================
+ Hits         17510    71827    +54317     
- Misses        5284    37673    +32389     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[acid-chicken]

スコープ的に適切かはわからないけど renoteId 指定時に text: " " (not "") とかだとまだ虚無ノートが作れる（引用になるが）

[acid-chicken]

post({ renoteId: some, text: " " }) zl assert(response.text === null) のテストケースが欲しいかも

[GrapeApple0]

text: '\n'でも虚無ノートに近いものが作れる気がします

[Sayamame-beans]

虚無ノート自体はゼロ幅スペースとかでも作れると思うので、nullと""以上の考慮はキリが無いような気がします…?
(そもそも引用で" "や"\n"を塞ぐ必要はあるのでしょうか…? 追記: リプライ+引用なら塞がない方が良さそうですが、引用のみのケースでは塞いでも塞がなくても良さそうな気がします。)

[Sayamame-beans]

そういえば、リプライでの引用において空のノート(text: ""と推測)を投稿したいというissueが出ていたのを思い出しました。これは別のノートにした内容を追加して補足としたい場合などに出番があります。

• 引用つきや画像付きのリプライでテキストが空でもnoteできるようにしてほしい #11744

参考までに…

[zyoshoka]

post({ renoteId: some, text: " " }) zl assert(response.text === null) のテストケースが欲しいかも

develop 最新では text が空白文字のみで構成されたリクエストに対して text: "" が返ってくるようになっているので、先にこれを直す必要がありそうです。renoteId または fileIds（mediaIds）または poll が null でない場合に、text が空白文字のみで構成されたリクエストになることを許可して、結果は text: null を返すようにすれば良さそうに思います。

text: '\n'でも虚無ノートに近いものが作れる気がします

虚無ノート自体はゼロ幅スペースとかでも作れると思うので、nullと""以上の考慮はキリが無いような気がします…?

とりあえず text に pattern: '[^\\s]+' を指定するようにしたので、本 PR では \s にマッチするような文字だけで構成されたリクエストはすべて弾くようになっています（ゼロ幅スペースなどの \s にマッチしない文字はもう放置で良い気がしています）¹。

そういえば、リプライでの引用において空のノート(text: ""と推測)を投稿したいというissueが出ていたのを思い出しました。

#11744 が出たのちに 961f5a0 が入りテキストが空でもノートできるようになったにも関わらず、この問題が未だ open になっているのは、text が null であって renoteId と replyId が null でないようなノートが、フロント側で普通のリノートとして表示されてしまっているのが問題となっているようなので、本 PR で修正しようかと思います²。 投稿フォームの UI など考慮すべき点が多そうだったので、本 PR では扱わないことにしました。

参考までに、develop 最新における仕様を掲げておきます。

develop 最新における仕様

renoteId (空欄は null)	fileIds または mediaIds (空欄は「省略されている」)	poll (空欄は null)	text: null	text: ""	text: " " text: "\\n" など
			200 text: null ($\color{red}\textbf{虚無ノート}$)	400	200 text: "" ($\color{red}\textbf{虚無ノート}$)
		null でない	200 text: null (投票のみのノート)	400	200 text: "" (投票のみのノート)
	省略されていない		200 text: null (ファイルのみのノート)	400	200 text: "" (ファイルのみのノート)
	省略されていない	null でない	200 text: null (ファイルと投票のノート)	400	200 text: "" (ファイルと投票のノート)
null でない			200 text: null (リノート)	400	200 text: "" ($\color{red}\textbf{虚無引用リノート}$)
null でない		null でない	200 text: null (投票のみの引用リノート)	400	200 text: "" (投票のみの引用リノート)
null でない	省略されていない		200 text: null (ファイルのみの引用リノート)	400	200 text: "" (ファイルのみの引用リノート)
null でない	省略されていない	null でない	200 text: null (ファイルと投票の引用リノート)	400	200 text: "" (ファイルと投票の引用リノート)

Footnotes

1. Ajv の pattern 評価には RegExp が用いられています。Node.js の採用している V8 において正規表現 \s に該当する文字の範囲は次のとおりです: https://github.com/nodejs/node/blob/af8ba373354137aef046b38d80cdccbcac8e95a7/deps/v8/src/regexp/regexp-compiler.h#L27-L30 ↩

2. ところで、develop 最新では text を空白文字のみで構成されたリクエストにすれば、リプライにおいてテキストが空であるような引用リノートを作成できます。 ↩

[zyoshoka]

#12969 (comment) を反映しました。

参考までに、本 PR における仕様を掲げておきます。

本 PR における仕様

renoteId (空欄は null)	fileIds または mediaIds (空欄は「省略されている」)	poll (空欄は null)	text: null	text: ""	text: " " text: "\\n" など
			400	400	400
		null でない	200 text: null (投票のみのノート)	400	200 text: null (投票のみのノート)
	省略されていない		200 text: null (ファイルのみのノート)	400	200 text: null (ファイルのみのノート)
	省略されていない	null でない	200 text: null (ファイルと投票のノート)	400	200 text: null (ファイルと投票のノート)
null でない			200 text: null (リノート)	400	200 text: null (リノート)
null でない		null でない	200 text: null (投票のみの引用リノート)	400	200 text: null (投票のみの引用リノート)
null でない	省略されていない		200 text: null (ファイルのみの引用リノート)	400	200 text: null (ファイルのみの引用リノート)
null でない	省略されていない	null でない	200 text: null (ファイルと投票の引用リノート)	400	200 text: null (ファイルと投票の引用リノート)

[github-actions]

api.jsonの差分作成中にエラーが発生しました。詳細はWorkflowのログを確認してください。

[zyoshoka]

OpenAPI Specification 3.1.0 対応に伴う変更点について記しておきます。

[zyoshoka]

swagger-cli は OpenAPI Specification 3.1.0 に対応せず deprecated となり、Redocly CLI への移行が公式に推奨されていた¹ので、そちらへの移行作業を行いました。

このコマンドは公式ドキュメントに載っていたマイグレーション・ガイド²に基づいています。

Footnotes

1. https://github.com/APIDevTools/swagger-cli#swaggeropenapi-cli ↩

2. https://redocly.com/docs/cli/guides/migrate-from-swagger-cli/#migrate-to-redocly-cli-from-swagger-cli ↩

[zyoshoka]

zyoshoka#4 にて validate-api-json が通っているのを確認済みです。

[zyoshoka]

OpenAPI Specification 3.1.0 では nullable が廃止され、type: null といった風の書式に変更されました¹。リクエストのスキーマを修正する必要がありましたが変更点があまりにも大きすぎてしまうので、その場しのぎの対処として convertSchemaToOpenApiSchema にかけるようにして書き換えを行っています。

Footnotes

1. 3.1.0-rc0 のリリースノート (https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0) の Breaking Change を参照してください。 ↩

[zyoshoka]

@apidevtools/swagger-parser が OpenAPI Specification 3.1.0 に対応していなかったので、これに対応していた fork の @readme/openapi-parser に移行しました。

[zyoshoka]

openapi-typescript は type: ['string', 'null'] と記述しても Union 型に null がつかないようになっている（仕様？）なので enum かつ nullable: true となっていた数箇所について enum への null 追記を行いました。

[Sayamame-beans]

(途中で追加の変更内容が生えたため、)changelogの更新を忘れてしまっているような気がします…?

[syuilo]

🙏🙏🙏

[tamaina]

（json-schema配下のschema、スクリプトで変換せずにそのまま全部OpenAPI v3準拠に書き換えればよかったのに）

[zyoshoka]

膨大になってしまう気がしたのでこの PR ではやらなかったんですが、自動でいい感じに全部書き換えられたらいいな・・・とは思っています（型チェックの問題も解消されそうですし）