merge 7.0.3 into main (#3945)

* V4 to v7 migration docs (#3933) * add files for migraiton docs * update migrate docs * add new docs to docs site * add docs for comment counts and data migration * update migration docs * replace v6 with v7 * add data migration documentation * rename migrate-intro * fix broken link * clarify data migration docs * update import mapper docs * update to 7.0.3 (#3944)
coralproject · May 10, 2022 · 594d05d · 594d05d
1 parent 7794dda
commit 594d05d
Show file tree

Hide file tree

Showing 10 changed files with 16,471 additions and 39 deletions.
diff --git a/docs/docs/external-moderation-phases.md b/docs/docs/external-moderation-phases.md
@@ -0,0 +1,234 @@
+---
+title: External Moderation Phases
+---
+
+# External Moderation Phases
+
+External Moderation Phases are an advanced feature that allows you to integrate with Coral's moderation pipeline via HTTP. You will provide a callback URL that will receive POST requests from Coral when comments are posted. The provided URl must respond with a moderation decision within the designated timeout or the action will be skipped.
+
+You can configure external moderation phases on your installation of Coral by
+visiting `/admin/configure/moderation/phases`.
+
+Once you've configured a external moderation phase in Coral, you will start to
+receive moderation requests in the form of a
+[External Moderation Requests](#external-moderation-request) at the provided
+callback URL. These will be in the form of `POST` requests with a `JSON`
+payload.
+
+When a comment is created or edited, it will be processed by moderation phases in
+a predefined order. Any external moderation phase is run last, and only if all
+other moderation phases before it do not return a status. The current set of
+moderation phases is listed in order [here](https://github.com/coralproject/talk/blob/main/src/core/server/services/comments/pipeline/phases/index.ts).
+
+Once you have received a moderation request, you must respond within the
+provided timeout else the phase will be skipped and it will continue. It is
+strongly recommended to [verify the request signature](#request-signing).
+
+The external moderation phase must respond with one of the following:
+
+1. Do not moderate the comment, and return a 204 without a body.
+2. Perform a moderation action and return a 200 with a [External Moderation Response](#external-moderation-response)
+   as a `JSON` encoded body containing the operations you want to perform on the
+   comment.
+
+## Request Signing
+
+Requests sent by Coral for external moderation phases use the same process as
+those used by webhooks. Refer to the [webhooks documentation](/webhooks)
+for instructions on how to verify signatures sent by Coral.
+
+## Schema
+
+### External Moderation Request
+
+```ts
+interface ExternalModerationRequest {
+  /**
+   * action refers to the specific operation being performed. If `NEW`, this
+   * is referring to a new comment being created. If `EDIT`, then this refers to
+   * an operation involving an edit operation on an existing Comment.
+   */
+  action: "NEW" | "EDIT";
+
+  /**
+   * comment refers to the actual Comment data for the Comment being
+   * created/edited.
+   */
+  comment: {
+    /**
+     * body refers to the actual body text of the Comment being created/edited.
+     */
+    body: string;
+
+    /**
+     * parentID is the identifier for the parent comment (if this Comment is a
+     * reply, null otherwise).
+     */
+    parentID: string | null;
+  };
+
+  /**
+   * author refers to the User that is creating/editing the Comment.
+   */
+  author: {
+    /**
+     * id is the identifier for this User.
+     */
+    id: string;
+
+    /**
+     * role refers to the role of this User.
+     */
+    role: "COMMENTER" | "STAFF" | "MODERATOR" | "ADMIN";
+  };
+
+  /**
+   * story refers to the Story being commented on.
+   */
+  story: {
+    /**
+     * id is the identifier for this Story.
+     */
+    id: string;
+
+    /**
+     * url is the URL for this Story.
+     */
+    url: string;
+  };
+
+  /**
+   * site refers to the Site that the story being commented on belongs to.
+   */
+  site: {
+    /**
+     * id is the identifier for this Site.
+     */
+    id: string;
+  };
+
+  /**
+   * tenantID is the identifer of the Tenant that this Comment is being
+   * created/edited on.
+   */
+  tenantID: string;
+
+  /**
+   * tenantDomain is the domain that is associated with this Tenant that this
+   * Comment is being created/edited on.
+   */
+  tenantDomain: string;
+}
+```
+
+#### Example
+
+New comment on a story:
+
+```json
+{
+  "action": "NEW",
+  "comment": {
+    "body": "Here's a comment!",
+    "parentID": null
+  },
+  "author": {
+    "id": "baf4e943-3594-4fcc-b2ba-3e8de7a76352",
+    "role": "COMMENTER"
+  },
+  "story": {
+    "id": "245b3856-b0a0-4d2f-a6bb-58c71f18d6a6",
+    "url": "http://localhost:1313/posts/a-story-url/"
+  },
+  "site": {
+    "id": "a4bede88-2d2c-4424-bc18-4322a9e285a6"
+  },
+  "tenantID": "19ba5794-7eeb-4d46-a81b-c00c61672501",
+  "tenantDomain": "localhost"
+}
+```
+
+New reply on a comment on a story:
+
+```json
+{
+  "action": "NEW",
+  "comment": {
+    "body": "Here's a reply!",
+    "parentID": "d79b787f-f406-49a0-a179-72e3652e54be"
+  },
+  "author": {
+    "id": "baf4e943-3594-4fcc-b2ba-3e8de7a76352",
+    "role": "COMMENTER"
+  },
+  "story": {
+    "id": "245b3856-b0a0-4d2f-a6bb-58c71f18d6a6",
+    "url": "http://localhost:1313/posts/a-story-url/"
+  },
+  "site": {
+    "id": "a4bede88-2d2c-4424-bc18-4322a9e285a6"
+  },
+  "tenantID": "19ba5794-7eeb-4d46-a81b-c00c61672501",
+  "tenantDomain": "localhost"
+}
+```
+
+### External Moderation Response
+
+```ts
+interface ExternalModerationResponse {
+  /**
+   * actions is an optional list of any flags to be added to this Comment.
+   */
+  actions?: Array<{
+    actionType: "FLAG";
+    reason: "COMMENT_DETECTED_TOXIC" | "COMMENT_DETECTED_SPAM";
+  }>;
+
+  /**
+   * tags are any listed tags that should be added to the comment.
+   */
+  tags?: Array<"FEATURED" | "STAFF">;
+
+  /**
+   * status when provided decides and terminates the moderation process by
+   * setting the status of the comment.
+   */
+  status?: "NONE" | "APPROVED" | "REJECTED" | "PREMOD" | "SYSTEM_WITHHELD";
+}
+```
+
+#### Examples
+
+Add a flag to a comment and do not set a status:
+
+```json
+{
+  "actions": [{ "actionType": "FLAG", "reason": "COMMENT_DETECTED_TOXIC" }]
+}
+```
+
+Reject a comment:
+
+```json
+{
+  "status": "REJECTED"
+}
+```
+
+Feature a comment and do not set a status:
+
+```json
+{
+  "tags": ["FEATURED"]
+}
+```
+
+Approve a comment and mark it as featured:
+
+```json
+{
+  "status": "APPROVED",
+  "tags": ["FEATURED"]
+}
+```
diff --git a/docs/docs/migrate-auth.md b/docs/docs/migrate-auth.md
@@ -0,0 +1,33 @@
+---
+title: "Migrating to v7: Auth strategies"
+---
+
+# Migrating to v7: Auth strategies
+
+Coral v7+ supports more authentication strategies than v4 out of the box with no plugins required. Read more about [social authentication strategies and OIDC (new)](/auth)
+
+## SSO in v7+
+
+In Legacy Coral, SSO authentication required:
+
+1. a service to generate JWTs
+2. a custom plugin to create and authenticate talk users from the JWTs
+
+In Coral v7+, user creation and authentication is handled by Coral, to authenticate, you need to generate a JWT that matches the Coral format, sign it with the secret provided by Coral, and pass that JWT to Coral in the embed code.
+
+Find out how to [generate a signed token](/sso). Note that the fields are different:
+
+- `jti`: now optional
+- `exp`: now optional
+- `iat`: **new** when the token was issued
+- `sub`: **deprecated** replaced by `user.id`
+- `user.email`: **new, required**
+- `user.username`: **new required**
+- `user.id`: **new required** replaces `sub`
+- `user.badges`: **new** optional
+- `user.role`: **new** optional
+- `user.url`: **new** optional
+- `iss`: **deprecated**
+- `aud`: **deprecated**
+
+[Read more about SSO configuration](/sso)
diff --git a/docs/docs/migrate-custom.md b/docs/docs/migrate-custom.md
@@ -0,0 +1,52 @@
+---
+title: "Migrating to v7: Replacing plugin functionality"
+---
+
+# Replacing plugin functionality
+
+Coral v7+ does not support custom plugins, however there are other options for customizing the functionality of the platform to suit your use cases. The functionality from all of the [default plugins](https://legacy.docs.coralproject.net/talk/plugins-directory/?q=default) is now built in to Coral.
+
+## External Moderation Phases
+
+External Moderation Phases allow you to hook into Coral's moderation pipeline and make moderation decisions programatically. If you were using a plugin to integrate with any automated moderation tools in v4, you would use an external moderaiton phase for that in v7+.
+
+[Read more about external moderation phases](/external-moderation-phases)
+
+## Webhooks
+
+Coral emits webhooks for Story Creation, Comment Creation, and Comment Reply Creation. You can configure Coral to send a webhook to a custom endpoint for any or all of these events.
+
+[Read more about webhooks](/webhooks)
+
+## Custom CSS
+
+Most visual customizations or most customizations to show or hide elements of the stream UI can be achieved thorugh custom CSS.
+
+[Read more about custom CSS](/css)
+
+## Replacements for specific plugins
+
+### talk-plugin-slack-notifications
+
+[Configure slack integration](/slack)
+
+### talk-plugin-akismet
+
+[Configure spam detection](/administration#spam-detection-filter)
+
+### talk-plugin-comment-content
+
+Coral v7 supports pasted links in comment content if they are valid. You can configure pre-moderation for all comments containing links via **Configuration > Moderation > Comments**.
+
+### talk-plugin-comment-count
+
+Coral v7 includes a script that will embed comment counts for a story on a given page via JSONP.
+[Learn more about the count script](/counts)
+
+### talk-plugin-toxic-comments
+
+[Configure the Toxic Comments Filter](/administration#toxic-comment-filter)
+
+### talk-plugin-rich-text
+
+Coral v7 includes optional rich-text by default, configure via **Configuration > General > Rich-text Comments**