From a5d06f518c86427e0b55752f23a95f7c3c22b750 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Tue, 16 Aug 2022 22:24:44 +0200 Subject: [PATCH 01/27] mv & link --- docs/{legacy => src/developer}/README.md | 0 .../developer}/developer/api-versioning.md | 0 .../developer/architecture/wire-arch-2.png | Bin .../developer/architecture/wire-arch-2.xml | 0 .../developer}/developer/cassandra-interaction.md | 0 .../developer}/developer/changelog.md | 0 .../developer}/developer/dependencies.md | 0 .../developer}/developer/editor-setup.md | 0 .../{legacy => src/developer}/developer/features.md | 0 .../developer/federation-api-conventions.md | 0 docs/{legacy => src/developer}/developer/how-to.md | 0 docs/{legacy => src/developer}/developer/linting.md | 0 .../developer}/developer/processes.md | 0 .../developer}/developer/scim/storage.md | 0 docs/{legacy => src/developer}/developer/servant.md | 0 docs/{legacy => src/developer}/developer/testing.md | 0 .../developer}/reference/cassandra-schema.cql | 0 .../developer}/reference/config-options.md | 0 .../developer}/reference/conversation.md | 0 .../developer}/reference/elastic-search.md | 0 .../reference/elasticsearch-migration-2021-02-16.md | 0 .../developer}/reference/make-docker-and-qemu.md | 0 .../developer}/reference/provisioning/scim-token.md | 0 .../reference/provisioning/scim-via-curl.md | 0 .../reference/provisioning/wire_scim_token.py | 0 .../developer}/reference/spar-braindump.md | 0 .../developer}/reference/team/legalhold.md | 0 .../developer}/reference/user/activation.md | 0 .../reference/user/connection-transitions.png | Bin .../reference/user/connection-transitions.xml | 0 .../developer}/reference/user/connection.md | 0 .../reference/user/connections-flow-1-backend.png | Bin .../developer}/reference/user/registration.md | 0 .../developer}/reference/user/rich-info.md | 0 docs/src/index.rst | 1 + 35 files changed, 1 insertion(+) rename docs/{legacy => src/developer}/README.md (100%) rename docs/{legacy => src/developer}/developer/api-versioning.md (100%) rename docs/{legacy => src/developer}/developer/architecture/wire-arch-2.png (100%) rename docs/{legacy => src/developer}/developer/architecture/wire-arch-2.xml (100%) rename docs/{legacy => src/developer}/developer/cassandra-interaction.md (100%) rename docs/{legacy => src/developer}/developer/changelog.md (100%) rename docs/{legacy => src/developer}/developer/dependencies.md (100%) rename docs/{legacy => src/developer}/developer/editor-setup.md (100%) rename docs/{legacy => src/developer}/developer/features.md (100%) rename docs/{legacy => src/developer}/developer/federation-api-conventions.md (100%) rename docs/{legacy => src/developer}/developer/how-to.md (100%) rename docs/{legacy => src/developer}/developer/linting.md (100%) rename docs/{legacy => src/developer}/developer/processes.md (100%) rename docs/{legacy => src/developer}/developer/scim/storage.md (100%) rename docs/{legacy => src/developer}/developer/servant.md (100%) rename docs/{legacy => src/developer}/developer/testing.md (100%) rename docs/{legacy => src/developer}/reference/cassandra-schema.cql (100%) rename docs/{legacy => src/developer}/reference/config-options.md (100%) rename docs/{legacy => src/developer}/reference/conversation.md (100%) rename docs/{legacy => src/developer}/reference/elastic-search.md (100%) rename docs/{legacy => src/developer}/reference/elasticsearch-migration-2021-02-16.md (100%) rename docs/{legacy => src/developer}/reference/make-docker-and-qemu.md (100%) rename docs/{legacy => src/developer}/reference/provisioning/scim-token.md (100%) rename docs/{legacy => src/developer}/reference/provisioning/scim-via-curl.md (100%) rename docs/{legacy => src/developer}/reference/provisioning/wire_scim_token.py (100%) rename docs/{legacy => src/developer}/reference/spar-braindump.md (100%) rename docs/{legacy => src/developer}/reference/team/legalhold.md (100%) rename docs/{legacy => src/developer}/reference/user/activation.md (100%) rename docs/{legacy => src/developer}/reference/user/connection-transitions.png (100%) rename docs/{legacy => src/developer}/reference/user/connection-transitions.xml (100%) rename docs/{legacy => src/developer}/reference/user/connection.md (100%) rename docs/{legacy => src/developer}/reference/user/connections-flow-1-backend.png (100%) rename docs/{legacy => src/developer}/reference/user/registration.md (100%) rename docs/{legacy => src/developer}/reference/user/rich-info.md (100%) diff --git a/docs/legacy/README.md b/docs/src/developer/README.md similarity index 100% rename from docs/legacy/README.md rename to docs/src/developer/README.md diff --git a/docs/legacy/developer/api-versioning.md b/docs/src/developer/developer/api-versioning.md similarity index 100% rename from docs/legacy/developer/api-versioning.md rename to docs/src/developer/developer/api-versioning.md diff --git a/docs/legacy/developer/architecture/wire-arch-2.png b/docs/src/developer/developer/architecture/wire-arch-2.png similarity index 100% rename from docs/legacy/developer/architecture/wire-arch-2.png rename to docs/src/developer/developer/architecture/wire-arch-2.png diff --git a/docs/legacy/developer/architecture/wire-arch-2.xml b/docs/src/developer/developer/architecture/wire-arch-2.xml similarity index 100% rename from docs/legacy/developer/architecture/wire-arch-2.xml rename to docs/src/developer/developer/architecture/wire-arch-2.xml diff --git a/docs/legacy/developer/cassandra-interaction.md b/docs/src/developer/developer/cassandra-interaction.md similarity index 100% rename from docs/legacy/developer/cassandra-interaction.md rename to docs/src/developer/developer/cassandra-interaction.md diff --git a/docs/legacy/developer/changelog.md b/docs/src/developer/developer/changelog.md similarity index 100% rename from docs/legacy/developer/changelog.md rename to docs/src/developer/developer/changelog.md diff --git a/docs/legacy/developer/dependencies.md b/docs/src/developer/developer/dependencies.md similarity index 100% rename from docs/legacy/developer/dependencies.md rename to docs/src/developer/developer/dependencies.md diff --git a/docs/legacy/developer/editor-setup.md b/docs/src/developer/developer/editor-setup.md similarity index 100% rename from docs/legacy/developer/editor-setup.md rename to docs/src/developer/developer/editor-setup.md diff --git a/docs/legacy/developer/features.md b/docs/src/developer/developer/features.md similarity index 100% rename from docs/legacy/developer/features.md rename to docs/src/developer/developer/features.md diff --git a/docs/legacy/developer/federation-api-conventions.md b/docs/src/developer/developer/federation-api-conventions.md similarity index 100% rename from docs/legacy/developer/federation-api-conventions.md rename to docs/src/developer/developer/federation-api-conventions.md diff --git a/docs/legacy/developer/how-to.md b/docs/src/developer/developer/how-to.md similarity index 100% rename from docs/legacy/developer/how-to.md rename to docs/src/developer/developer/how-to.md diff --git a/docs/legacy/developer/linting.md b/docs/src/developer/developer/linting.md similarity index 100% rename from docs/legacy/developer/linting.md rename to docs/src/developer/developer/linting.md diff --git a/docs/legacy/developer/processes.md b/docs/src/developer/developer/processes.md similarity index 100% rename from docs/legacy/developer/processes.md rename to docs/src/developer/developer/processes.md diff --git a/docs/legacy/developer/scim/storage.md b/docs/src/developer/developer/scim/storage.md similarity index 100% rename from docs/legacy/developer/scim/storage.md rename to docs/src/developer/developer/scim/storage.md diff --git a/docs/legacy/developer/servant.md b/docs/src/developer/developer/servant.md similarity index 100% rename from docs/legacy/developer/servant.md rename to docs/src/developer/developer/servant.md diff --git a/docs/legacy/developer/testing.md b/docs/src/developer/developer/testing.md similarity index 100% rename from docs/legacy/developer/testing.md rename to docs/src/developer/developer/testing.md diff --git a/docs/legacy/reference/cassandra-schema.cql b/docs/src/developer/reference/cassandra-schema.cql similarity index 100% rename from docs/legacy/reference/cassandra-schema.cql rename to docs/src/developer/reference/cassandra-schema.cql diff --git a/docs/legacy/reference/config-options.md b/docs/src/developer/reference/config-options.md similarity index 100% rename from docs/legacy/reference/config-options.md rename to docs/src/developer/reference/config-options.md diff --git a/docs/legacy/reference/conversation.md b/docs/src/developer/reference/conversation.md similarity index 100% rename from docs/legacy/reference/conversation.md rename to docs/src/developer/reference/conversation.md diff --git a/docs/legacy/reference/elastic-search.md b/docs/src/developer/reference/elastic-search.md similarity index 100% rename from docs/legacy/reference/elastic-search.md rename to docs/src/developer/reference/elastic-search.md diff --git a/docs/legacy/reference/elasticsearch-migration-2021-02-16.md b/docs/src/developer/reference/elasticsearch-migration-2021-02-16.md similarity index 100% rename from docs/legacy/reference/elasticsearch-migration-2021-02-16.md rename to docs/src/developer/reference/elasticsearch-migration-2021-02-16.md diff --git a/docs/legacy/reference/make-docker-and-qemu.md b/docs/src/developer/reference/make-docker-and-qemu.md similarity index 100% rename from docs/legacy/reference/make-docker-and-qemu.md rename to docs/src/developer/reference/make-docker-and-qemu.md diff --git a/docs/legacy/reference/provisioning/scim-token.md b/docs/src/developer/reference/provisioning/scim-token.md similarity index 100% rename from docs/legacy/reference/provisioning/scim-token.md rename to docs/src/developer/reference/provisioning/scim-token.md diff --git a/docs/legacy/reference/provisioning/scim-via-curl.md b/docs/src/developer/reference/provisioning/scim-via-curl.md similarity index 100% rename from docs/legacy/reference/provisioning/scim-via-curl.md rename to docs/src/developer/reference/provisioning/scim-via-curl.md diff --git a/docs/legacy/reference/provisioning/wire_scim_token.py b/docs/src/developer/reference/provisioning/wire_scim_token.py similarity index 100% rename from docs/legacy/reference/provisioning/wire_scim_token.py rename to docs/src/developer/reference/provisioning/wire_scim_token.py diff --git a/docs/legacy/reference/spar-braindump.md b/docs/src/developer/reference/spar-braindump.md similarity index 100% rename from docs/legacy/reference/spar-braindump.md rename to docs/src/developer/reference/spar-braindump.md diff --git a/docs/legacy/reference/team/legalhold.md b/docs/src/developer/reference/team/legalhold.md similarity index 100% rename from docs/legacy/reference/team/legalhold.md rename to docs/src/developer/reference/team/legalhold.md diff --git a/docs/legacy/reference/user/activation.md b/docs/src/developer/reference/user/activation.md similarity index 100% rename from docs/legacy/reference/user/activation.md rename to docs/src/developer/reference/user/activation.md diff --git a/docs/legacy/reference/user/connection-transitions.png b/docs/src/developer/reference/user/connection-transitions.png similarity index 100% rename from docs/legacy/reference/user/connection-transitions.png rename to docs/src/developer/reference/user/connection-transitions.png diff --git a/docs/legacy/reference/user/connection-transitions.xml b/docs/src/developer/reference/user/connection-transitions.xml similarity index 100% rename from docs/legacy/reference/user/connection-transitions.xml rename to docs/src/developer/reference/user/connection-transitions.xml diff --git a/docs/legacy/reference/user/connection.md b/docs/src/developer/reference/user/connection.md similarity index 100% rename from docs/legacy/reference/user/connection.md rename to docs/src/developer/reference/user/connection.md diff --git a/docs/legacy/reference/user/connections-flow-1-backend.png b/docs/src/developer/reference/user/connections-flow-1-backend.png similarity index 100% rename from docs/legacy/reference/user/connections-flow-1-backend.png rename to docs/src/developer/reference/user/connections-flow-1-backend.png diff --git a/docs/legacy/reference/user/registration.md b/docs/src/developer/reference/user/registration.md similarity index 100% rename from docs/legacy/reference/user/registration.md rename to docs/src/developer/reference/user/registration.md diff --git a/docs/legacy/reference/user/rich-info.md b/docs/src/developer/reference/user/rich-info.md similarity index 100% rename from docs/legacy/reference/user/rich-info.md rename to docs/src/developer/reference/user/rich-info.md diff --git a/docs/src/index.rst b/docs/src/index.rst index 8750a458584..a5b0058de77 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -26,6 +26,7 @@ This documentation may be expanded in the future to cover other aspects of Wire. How to set up user provisioning with LDAP or SCIM Client API documentation Security responses + Notes for developers .. Overview From 4edd39cab272bb430f59d577fad9e5798b8b605a Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Tue, 16 Aug 2022 22:30:36 +0200 Subject: [PATCH 02/27] tweak --- docs/src/developer/README.md | 44 ++++++++++++++++++- .../src/developer/developer/api-versioning.md | 2 +- 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/src/developer/README.md b/docs/src/developer/README.md index 650b2b0baae..9803c6d881d 100644 --- a/docs/src/developer/README.md +++ b/docs/src/developer/README.md @@ -1,6 +1,48 @@ # Reference documentation -What you need to know as a user of the Wire backend: concepts, features, and API. We strive to keep these up to date. +What you need to know as a user of the Wire backend: concepts, +features, and API. We want to keep these up to date. They could +benefit from some re-ordering, and they are far from complete, but we +hope they will still help you. + +## TOC + +### developer + +* [api-versioning.md](./developer/api-versioning.md) +* [cassandra-interaction.md](./developer/cassandra-interaction.md) +* [changelog.md](./developer/changelog.md) +* [dependencies.md](./developer/dependencies.md) +* [editor-setup.md](./developer/editor-setup.md) +* [features.md](./developer/features.md) +* [federation-api-conventions.md](./developer/federation-api-conventions.md) +* [how-to.md](./developer/how-to.md) +* [linting.md](./developer/linting.md) +* [processes.md](./developer/processes.md) +* [scim/storage.md](./developer/scim/storage.md) +* [servant.md](./developer/servant.md) +* [testing.md](./developer/testing.md) + +### reference + +* [config-options.md](./reference/config-options.md) +* [conversation.md](./reference/conversation.md) +* [elastic-search.md](./reference/elastic-search.md) +* [elasticsearch-migration-2021-02-16.md](./reference/elasticsearch-migration-2021-02-16.md) +* [make-docker-and-qemu.md](./reference/make-docker-and-qemu.md) +* [provisioning/scim-token.md](./reference/provisioning/scim-token.md) +* [provisioning/scim-via-curl.md](./reference/provisioning/scim-via-curl.md) +* [provisioning/wire_scim_token.py](./reference/provisioning/wire_scim_token.py) +* [spar-braindump.md](./reference/spar-braindump.md) +* [team/legalhold.md](./reference/team/legalhold.md) +* [user/activation.md](./reference/user/activation.md) +* [user/connection.md](./reference/user/connection.md) +* [user/connections-flow-1-backend.png](./reference/user/connections-flow-1-backend.png) +* [user/connection-transitions.png](./reference/user/connection-transitions.png) +* [user/connection-transitions.xml](./reference/user/connection-transitions.xml) +* [user/registration.md](./reference/user/registration.md) +* [user/rich-info.md](./reference/user/rich-info.md) + ## Users diff --git a/docs/src/developer/developer/api-versioning.md b/docs/src/developer/developer/api-versioning.md index 1bae9bfe46a..6e1f3d75b31 100644 --- a/docs/src/developer/developer/api-versioning.md +++ b/docs/src/developer/developer/api-versioning.md @@ -16,7 +16,7 @@ A backend advertises a set of *supported* API versions, divided into a set of be discovered via the `GET /api-version` endpoint, which returns a JSON object of the form: -```json +``` { "supported": [0, 1, 2, 3, 4], "development": [4], ... From 226a7c653ac66eca2760d7f53355961fffd87fd6 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 17 Aug 2022 16:36:04 +0200 Subject: [PATCH 03/27] tweak more. --- docs/src/developer/README.md | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/docs/src/developer/README.md b/docs/src/developer/README.md index 9803c6d881d..950d4ae9716 100644 --- a/docs/src/developer/README.md +++ b/docs/src/developer/README.md @@ -1,4 +1,4 @@ -# Reference documentation +# Notes for developers What you need to know as a user of the Wire backend: concepts, features, and API. We want to keep these up to date. They could @@ -56,20 +56,6 @@ User profiles and metadata: * [Connections between users](reference/user/connection.md) `{#RefConnection}` * [Rich info](reference/user/rich-info.md) `{#RefRichInfo}` -TODO. - -## Teams - -TODO. - -## Messaging - -TODO. - -## Single sign-on - -TODO. - ## SCIM provisioning We have support for provisioning users via SCIM ([RFC 7664][], [RFC 7643][]). It's in the beta stage. @@ -80,7 +66,7 @@ We have support for provisioning users via SCIM ([RFC 7664][], [RFC 7643][]). It * [Using the SCIM API with curl](reference/provisioning/scim-via-curl.md) `{#RefScimViaCurl}` * [Authentication via SCIM tokens](reference/provisioning/scim-token.md) `{#RefScimToken}` -# Developer documentation +## Hints Internal documentation detailing what you need to know as a Wire backend developer. All of these documents can and should be referenced in the code. @@ -89,7 +75,6 @@ If you're not a member of the Wire backend team, you might still find these docu * [Development setup](developer/dependencies.md) `{#DevDeps}` * [Editor setup](developer/editor-setup.md) `{#DevEditor}` * [Storing SCIM-related data](developer/scim/storage.md) `{#DevScimStorage}` -* TODO ## Cassandra From a6b01fee53d778359fc87833e01349c958b97fac Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 17 Aug 2022 16:40:52 +0200 Subject: [PATCH 04/27] Fixup --- docs/src/developer/developer/changelog.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/src/developer/developer/changelog.md b/docs/src/developer/developer/changelog.md index 886df37964a..f6477ec1620 100644 --- a/docs/src/developer/developer/changelog.md +++ b/docs/src/developer/developer/changelog.md @@ -1,3 +1,5 @@ +# changelog + The wire-server repo has a process for changelog editing that prevents merge conflicts and enforces a consistent structure to the release notes. From 73136176db33cfd7373a39ee94b9d21aabedf075 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 17 Aug 2022 16:56:43 +0200 Subject: [PATCH 05/27] not sure we want to keep this --- docs/src/developer/README.md | 90 --------------- docs/src/developer/index.rst | 104 ++++++++++++++++++ ...{wire_scim_token.py => wire_scim_token.md} | 4 + docs/src/index.rst | 2 +- 4 files changed, 109 insertions(+), 91 deletions(-) delete mode 100644 docs/src/developer/README.md create mode 100644 docs/src/developer/index.rst rename docs/src/developer/reference/provisioning/{wire_scim_token.py => wire_scim_token.md} (99%) mode change 100755 => 100644 diff --git a/docs/src/developer/README.md b/docs/src/developer/README.md deleted file mode 100644 index 950d4ae9716..00000000000 --- a/docs/src/developer/README.md +++ /dev/null @@ -1,90 +0,0 @@ -# Notes for developers - -What you need to know as a user of the Wire backend: concepts, -features, and API. We want to keep these up to date. They could -benefit from some re-ordering, and they are far from complete, but we -hope they will still help you. - -## TOC - -### developer - -* [api-versioning.md](./developer/api-versioning.md) -* [cassandra-interaction.md](./developer/cassandra-interaction.md) -* [changelog.md](./developer/changelog.md) -* [dependencies.md](./developer/dependencies.md) -* [editor-setup.md](./developer/editor-setup.md) -* [features.md](./developer/features.md) -* [federation-api-conventions.md](./developer/federation-api-conventions.md) -* [how-to.md](./developer/how-to.md) -* [linting.md](./developer/linting.md) -* [processes.md](./developer/processes.md) -* [scim/storage.md](./developer/scim/storage.md) -* [servant.md](./developer/servant.md) -* [testing.md](./developer/testing.md) - -### reference - -* [config-options.md](./reference/config-options.md) -* [conversation.md](./reference/conversation.md) -* [elastic-search.md](./reference/elastic-search.md) -* [elasticsearch-migration-2021-02-16.md](./reference/elasticsearch-migration-2021-02-16.md) -* [make-docker-and-qemu.md](./reference/make-docker-and-qemu.md) -* [provisioning/scim-token.md](./reference/provisioning/scim-token.md) -* [provisioning/scim-via-curl.md](./reference/provisioning/scim-via-curl.md) -* [provisioning/wire_scim_token.py](./reference/provisioning/wire_scim_token.py) -* [spar-braindump.md](./reference/spar-braindump.md) -* [team/legalhold.md](./reference/team/legalhold.md) -* [user/activation.md](./reference/user/activation.md) -* [user/connection.md](./reference/user/connection.md) -* [user/connections-flow-1-backend.png](./reference/user/connections-flow-1-backend.png) -* [user/connection-transitions.png](./reference/user/connection-transitions.png) -* [user/connection-transitions.xml](./reference/user/connection-transitions.xml) -* [user/registration.md](./reference/user/registration.md) -* [user/rich-info.md](./reference/user/rich-info.md) - - -## Users - -User lifecycle: - -* [User registration](reference/user/registration.md) `{#RefRegistration}` -* [User activation](reference/user/activation.md) `{#RefActivation}` - -User profiles and metadata: - -* [Connections between users](reference/user/connection.md) `{#RefConnection}` -* [Rich info](reference/user/rich-info.md) `{#RefRichInfo}` - -## SCIM provisioning - -We have support for provisioning users via SCIM ([RFC 7664][], [RFC 7643][]). It's in the beta stage. - -[RFC 7664]: https://tools.ietf.org/html/rfc7664 -[RFC 7643]: https://tools.ietf.org/html/rfc7643 - -* [Using the SCIM API with curl](reference/provisioning/scim-via-curl.md) `{#RefScimViaCurl}` -* [Authentication via SCIM tokens](reference/provisioning/scim-token.md) `{#RefScimToken}` - -## Hints - -Internal documentation detailing what you need to know as a Wire backend developer. All of these documents can and should be referenced in the code. - -If you're not a member of the Wire backend team, you might still find these documents useful, but keep in mind that they are a work in progress. - -* [Development setup](developer/dependencies.md) `{#DevDeps}` -* [Editor setup](developer/editor-setup.md) `{#DevEditor}` -* [Storing SCIM-related data](developer/scim/storage.md) `{#DevScimStorage}` - -## Cassandra - -We use [Cassandra](http://cassandra.apache.org/) as the primary data store. It is scalable, has very fast reads and writes, and is conceptually simple (or at least simpler than SQL databases). - -Some helpful links: - -* [Query syntax](https://docs.datastax.com/en/cql/3.3/cql/cql_reference/cqlReferenceTOC.html) - -* How deletes work in Cassandra: - - - [Understanding Deletes](https://medium.com/@foundev/domain-modeling-around-deletes-1cc9b6da0d24) - - [Cassandra Compaction and Tombstone Behavior](http://engblog.polyvore.com/2015/03/cassandra-compaction-and-tombstone.html) diff --git a/docs/src/developer/index.rst b/docs/src/developer/index.rst new file mode 100644 index 00000000000..8ca10233fcd --- /dev/null +++ b/docs/src/developer/index.rst @@ -0,0 +1,104 @@ +Notes for developers +==================== + +What you need to know as a user of the Wire backend: concepts, features, +and API. We want to keep these up to date. They could benefit from some +re-ordering, and they are far from complete, but we hope they will still +help you. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + :glob: + + developer/api-versioning.md <./developer/api-versioning.md> + developer/assandra-interaction.md <./developer/cassandra-interaction.md> + developer/changelog.md <./developer/changelog.md> + developer/dependencies.md <./developer/dependencies.md> + developer/editor-setup.md <./developer/editor-setup.md> + developer/features.md <./developer/features.md> + developer/federation-api-conventions.md <./developer/federation-api-conventions.md> + developer/how-to.md <./developer/how-to.md> + developer/linting.md <./developer/linting.md> + developer/processes.md <./developer/processes.md> + developer/scim/storage.md <./developer/scim/storage.md> + developer/servant.md <./developer/servant.md> + developer/testing.md <./developer/testing.md> + reference/config-options.md <./reference/config-options.md> + reference/conversation.md <./reference/conversation.md> + reference/elastic-search.md <./reference/elastic-search.md> + reference/elasticsearch-migration-2021-02-16.md <./reference/elasticsearch-migration-2021-02-16.md> + reference/make-docker-and-qemu.md <./reference/make-docker-and-qemu.md> + reference/provisioning/scim-token.md <./reference/provisioning/scim-token.md> + reference/provisioning/scim-via-curl.md <./reference/provisioning/scim-via-curl.md> + reference/provisioning/wire_scim_token.md <./reference/provisioning/wire_scim_token.md> + reference/spar-braindump.md <./reference/spar-braindump.md> + reference/team/legalhold.md <./reference/team/legalhold.md> + reference/user/activation.md <./reference/user/activation.md> + reference/user/connection.md <./reference/user/connection.md> + reference/user/registration.md <./reference/user/registration.md> + reference/user/rich-info.md <./reference/user/rich-info.md> + +Users +----- + +User lifecycle: + +- `User registration `__ + ``{#RefRegistration}`` +- `User activation `__ + ``{#RefActivation}`` + +User profiles and metadata: + +- `Connections between users `__ + ``{#RefConnection}`` +- `Rich info `__ ``{#RefRichInfo}`` + +SCIM provisioning +----------------- + +We have support for provisioning users via SCIM (`RFC +7664 `__, `RFC +7643 `__). It’s in the beta stage. + +- `Using the SCIM API with + curl `__ + ``{#RefScimViaCurl}`` +- `Authentication via SCIM + tokens `__ ``{#RefScimToken}`` + +Hints +----- + +Internal documentation detailing what you need to know as a Wire backend +developer. All of these documents can and should be referenced in the +code. + +If you’re not a member of the Wire backend team, you might still find +these documents useful, but keep in mind that they are a work in +progress. + +- `Development setup `__ ``{#DevDeps}`` +- `Editor setup `__ ``{#DevEditor}`` +- `Storing SCIM-related data `__ + ``{#DevScimStorage}`` + +Cassandra +--------- + +We use `Cassandra `__ as the primary data +store. It is scalable, has very fast reads and writes, and is +conceptually simple (or at least simpler than SQL databases). + +Some helpful links: + +- `Query + syntax `__ + +- How deletes work in Cassandra: + + - `Understanding + Deletes `__ + - `Cassandra Compaction and Tombstone + Behavior `__ diff --git a/docs/src/developer/reference/provisioning/wire_scim_token.py b/docs/src/developer/reference/provisioning/wire_scim_token.md old mode 100755 new mode 100644 similarity index 99% rename from docs/src/developer/reference/provisioning/wire_scim_token.py rename to docs/src/developer/reference/provisioning/wire_scim_token.md index 2823a7bbca8..62222ed9973 --- a/docs/src/developer/reference/provisioning/wire_scim_token.py +++ b/docs/src/developer/reference/provisioning/wire_scim_token.md @@ -1,3 +1,6 @@ +Some python code + +``` #!/usr/bin/env python3 # # This file is part of the Wire Server implementation. @@ -105,3 +108,4 @@ def main(): if __name__ == '__main__': main() +``` diff --git a/docs/src/index.rst b/docs/src/index.rst index a5b0058de77..d3f356dd33d 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -26,7 +26,7 @@ This documentation may be expanded in the future to cover other aspects of Wire. How to set up user provisioning with LDAP or SCIM Client API documentation Security responses - Notes for developers + Notes for developers .. Overview From 1e055b4e78840fe003deb472519a203e96c1c5d5 Mon Sep 17 00:00:00 2001 From: fisx Date: Mon, 22 Aug 2022 15:07:43 +0200 Subject: [PATCH 06/27] Update docs/src/developer/index.rst Co-authored-by: yupri <69316518+yu-pri@users.noreply.github.com> --- docs/src/developer/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/developer/index.rst b/docs/src/developer/index.rst index 8ca10233fcd..44c904a74f4 100644 --- a/docs/src/developer/index.rst +++ b/docs/src/developer/index.rst @@ -12,7 +12,7 @@ help you. :glob: developer/api-versioning.md <./developer/api-versioning.md> - developer/assandra-interaction.md <./developer/cassandra-interaction.md> + developer/cassandra-interaction.md <./developer/cassandra-interaction.md> developer/changelog.md <./developer/changelog.md> developer/dependencies.md <./developer/dependencies.md> developer/editor-setup.md <./developer/editor-setup.md> From 72a7905f0fa451d818581c75c7fd2f1ce0e4b32c Mon Sep 17 00:00:00 2001 From: Arthur Wolf Date: Mon, 22 Aug 2022 18:29:46 +0200 Subject: [PATCH 07/27] changing levels of headings to remove warning --- docs/src/developer/developer/features.md | 2 +- docs/src/developer/developer/testing.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/src/developer/developer/features.md b/docs/src/developer/developer/features.md index a07f505d4d3..d560b441626 100644 --- a/docs/src/developer/developer/features.md +++ b/docs/src/developer/developer/features.md @@ -1,4 +1,4 @@ -## Features +# Features Wire has multiple features (or feature flags) that affect the behaviour of backend and clients, e.g. `sso`, `searchVisibility`, `digitalSignatures`, diff --git a/docs/src/developer/developer/testing.md b/docs/src/developer/developer/testing.md index 0e41f8920bf..d36be1808b5 100644 --- a/docs/src/developer/developer/testing.md +++ b/docs/src/developer/developer/testing.md @@ -1,4 +1,4 @@ -## Testing the wire-server Haskell code base +# Testing the wire-server Haskell code base Every package in this repository should have one or more directories named `test` or `test*`. Ideally, there are at least unit tests @@ -6,19 +6,19 @@ named `test` or `test*`. Ideally, there are at least unit tests integration tests (eg. `test/integration`) for packages with executables (`/services`). -### General rule +## General rule Write as much pure code as possible. If you write a function that has an effect only in a small part of its implementation, write a pure function instead, and call if from an effectful function. -### Unit tests +## Unit tests All data types that are serialized ([`ToByteString`](https://hackage.haskell.org/package/amazonka-core-1.6.1/docs/Network-AWS-Data-ByteString.html#t:ToByteString), [`ToByteString`](https://hackage.haskell.org/package/aeson/docs/Data-Aeson.html#t:ToJSON), swagger, cassandra, ...) should have roundtrip quickcheck tests like [here](https://github.com/wireapp/wire-server/blob/develop/libs/wire-api/test/unit/Test/Wire/API/Roundtrip/Aeson.hs#L235). All pure functions `f` that do something interesting should have a couple of tests of the form `shouldBe (f ) ` to cover corner cases. If code is refactored, all the effects should be mocked with polysemy or mtl, the old implementation should be moved to the test suite, and there should be quickcheck tests running the new implementation against the old and comparing results ([example](https://github.com/wireapp/wire-server/blob/develop/services/gundeck/test/unit/MockGundeck.hs)). -### Integration tests +## Integration tests - All new rest API end-points need to be called a few times to cover as much of the corner cases as feasible. - We have machinery to set up scaffolding teams and modify context such as server configuration files where needed. Look through the existing code for inspiration. From 73549cb81c931a618d95d21478a9ada4ddb28ef1 Mon Sep 17 00:00:00 2001 From: Arthur Wolf Date: Mon, 22 Aug 2022 18:33:09 +0200 Subject: [PATCH 08/27] changing levels of headings to remove warning --- docs/src/developer/developer/cassandra-interaction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/developer/developer/cassandra-interaction.md b/docs/src/developer/developer/cassandra-interaction.md index 8cc9d3ee514..9ff05e06517 100644 --- a/docs/src/developer/developer/cassandra-interaction.md +++ b/docs/src/developer/developer/cassandra-interaction.md @@ -2,7 +2,7 @@ -* [Anti-patterns](#anti-patterns) +* [Anti-patterns](anti-patterns) * [Anti-pattern: Using full table scans in production code](#anti-pattern-using-full-table-scans-in-production-code) * [Anti-pattern: Using IN queries on a field in the partition key](#anti-pattern-using-in-queries-on-a-field-in-the-partition-key) * [Anti-pattern: Designing for a lot of deletes or updates](#anti-pattern-designing-for-a-lot-of-deletes-or-updates) From 058ec06cbffa9c57cdfab796f4b2aa7715cd7dfe Mon Sep 17 00:00:00 2001 From: Arthur Wolf Date: Mon, 22 Aug 2022 18:36:59 +0200 Subject: [PATCH 09/27] fixing a problem with internal headers not creating references, as per myst docs --- docs/src/conf.py | 3 +++ docs/src/developer/developer/cassandra-interaction.md | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index 777df273f2e..800d098ba99 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -111,3 +111,6 @@ smv_outputdir_format = 'versions/{ref.name}' smv_prefer_remote_refs = True + +# As per https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=anchor#auto-generated-header-anchors +myst_heading_anchors = 3 diff --git a/docs/src/developer/developer/cassandra-interaction.md b/docs/src/developer/developer/cassandra-interaction.md index 9ff05e06517..8cc9d3ee514 100644 --- a/docs/src/developer/developer/cassandra-interaction.md +++ b/docs/src/developer/developer/cassandra-interaction.md @@ -2,7 +2,7 @@ -* [Anti-patterns](anti-patterns) +* [Anti-patterns](#anti-patterns) * [Anti-pattern: Using full table scans in production code](#anti-pattern-using-full-table-scans-in-production-code) * [Anti-pattern: Using IN queries on a field in the partition key](#anti-pattern-using-in-queries-on-a-field-in-the-partition-key) * [Anti-pattern: Designing for a lot of deletes or updates](#anti-pattern-designing-for-a-lot-of-deletes-or-updates) From 24b4d85cec0a74f7fcedd5fdecd1f6624870c372 Mon Sep 17 00:00:00 2001 From: Arthur Wolf Date: Mon, 22 Aug 2022 18:40:27 +0200 Subject: [PATCH 10/27] fixed minor warnings --- docs/src/conf.py | 2 +- docs/src/developer/developer/dependencies.md | 2 +- docs/src/developer/developer/editor-setup.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index 800d098ba99..cd6e8343d19 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -113,4 +113,4 @@ smv_prefer_remote_refs = True # As per https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=anchor#auto-generated-header-anchors -myst_heading_anchors = 3 +myst_heading_anchors = 4 diff --git a/docs/src/developer/developer/dependencies.md b/docs/src/developer/developer/dependencies.md index 27322255d0c..b9bec91c534 100644 --- a/docs/src/developer/developer/dependencies.md +++ b/docs/src/developer/developer/dependencies.md @@ -112,7 +112,7 @@ sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_heade Please refer to [Stack's installation instructions](https://docs.haskellstack.org/en/stable/README/#how-to-install). -When you're done, ensure `stack --version` is the same as `STACK_VERSION` in [`build/ubuntu/Dockerfile.prebuilder`](../../build/ubuntu/Dockerfile.prebuilder). +When you're done, ensure `stack --version` is the same as `STACK_VERSION` in [`build/ubuntu/Dockerfile.prebuilder`](https://github.com/wireapp/wire-server/blob/develop/build/ubuntu/Dockerfile.prebuilder). If you have to, you can downgrade stack with this command: diff --git a/docs/src/developer/developer/editor-setup.md b/docs/src/developer/developer/editor-setup.md index 4e030f88b08..6e621defcc3 100644 --- a/docs/src/developer/developer/editor-setup.md +++ b/docs/src/developer/developer/editor-setup.md @@ -61,7 +61,7 @@ Install the [projectile][] package for Emacs and do `M-x projectile-add-known-pr To use HLS bundled in direnv setup, here is a sample `.dir-locals.el` that can be put in the root directory of the project: -```el +``` ((haskell-mode . ((haskell-completion-backend . lsp) (lsp-haskell-server-path . "/home/haskeller/code/wire-server/hack/bin/nix-hls.sh") ))) From c7926c3cb9d675e44e3d4e1cf54c701241ec1bca Mon Sep 17 00:00:00 2001 From: Arthur Wolf Date: Mon, 22 Aug 2022 18:43:23 +0200 Subject: [PATCH 11/27] more references minor fixes --- docs/src/developer/developer/how-to.md | 2 +- docs/src/developer/developer/servant.md | 2 +- docs/src/developer/reference/config-options.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/developer/developer/how-to.md b/docs/src/developer/developer/how-to.md index aa40ccdd2ae..87c60e278c5 100644 --- a/docs/src/developer/developer/how-to.md +++ b/docs/src/developer/developer/how-to.md @@ -9,7 +9,7 @@ Terminal 1: Terminal 2: * Compile all services: `make services` - * Note that you have to [import the public signing keys for nginx](../../services/nginz/README.md#common-problems-while-compiling) to be able to build nginz + * Note that you have to [import the public signing keys for nginx](https://github.com/wireapp/wire-server/blob/develop/services/nginz/README.md#common-problems-while-compiling) to be able to build nginz * Run services including nginz: `export INTEGRATION_USE_NGINZ=1; ./services/start-services-only.sh` Open your browser at: diff --git a/docs/src/developer/developer/servant.md b/docs/src/developer/developer/servant.md index 0b577f7f2cf..426b7b89fb7 100644 --- a/docs/src/developer/developer/servant.md +++ b/docs/src/developer/developer/servant.md @@ -4,7 +4,7 @@ We currently use Servant for the public (i.e. client-facing) API in brig, galley Client-facing APIs are defined in `Wire.API.Routes.Public.{Brig,Galley}`. Internal APIs are all over the place at the moment. Federation APIs are in `Wire.API.Federation.API.{Brig,Galley}`. -Our APIs are able to generate Swagger documentation semi-automatically using `servant-swagger2`. The `schema-profunctor` library (see [`README.md`](/libs/schema-profunctor/README.md) in `libs/schema-profunctor`) is used to create "schemas" for the input and output types used in the Servant APIs. A schema contains all the information needed to serialise/deserialise JSON values, as well as the documentation and metadata needed to generate Swagger. +Our APIs are able to generate Swagger documentation semi-automatically using `servant-swagger2`. The `schema-profunctor` library (see [`README.md`](https://github.com/wireapp/wire-server/blob/develop/libs/schema-profunctor/README.md) in `libs/schema-profunctor`) is used to create "schemas" for the input and output types used in the Servant APIs. A schema contains all the information needed to serialise/deserialise JSON values, as well as the documentation and metadata needed to generate Swagger. # Combinators diff --git a/docs/src/developer/reference/config-options.md b/docs/src/developer/reference/config-options.md index 33d8eb04445..03ea91c9eaa 100644 --- a/docs/src/developer/reference/config-options.md +++ b/docs/src/developer/reference/config-options.md @@ -258,7 +258,7 @@ mls: ``` -This default configuration can be overriden on a per-team basis through the [feature config API](./features.md) +This default configuration can be overriden on a per-team basis through the [feature config API](../developer/features.md) ### Federation Domain From 6d3d4b4254ce752a61ee76e6c12a8a251b347f42 Mon Sep 17 00:00:00 2001 From: Arthur Wolf Date: Mon, 22 Aug 2022 18:56:47 +0200 Subject: [PATCH 12/27] fix many reference warnings --- .../src/developer/reference/elastic-search.md | 2 +- .../src/developer/reference/spar-braindump.md | 6 ++-- .../developer/reference/user/activation.md | 34 ++++++++++++------- .../developer/reference/user/connection.md | 31 +++++++++++------ .../developer/reference/user/registration.md | 22 +++++++----- .../src/developer/reference/user/rich-info.md | 2 +- 6 files changed, 60 insertions(+), 37 deletions(-) diff --git a/docs/src/developer/reference/elastic-search.md b/docs/src/developer/reference/elastic-search.md index 246988ec014..82b061fbfb4 100644 --- a/docs/src/developer/reference/elastic-search.md +++ b/docs/src/developer/reference/elastic-search.md @@ -123,7 +123,7 @@ Now you can delete the old index. **NOTE**: There is a bug hidden when using this way. Sometimes a user won't get deleted from the index. Attempts at reproducing this issue in a simpler environment have failed. As a workaround, there is a tool in -[tools/db/find-undead](../../tools/db/find-undead) which can be used to find the +[tools/db/find-undead](https://github.com/wireapp/wire-server/tree/develop/tools/db/find-undead) which can be used to find the undead users right after the migration. If they exist, please run refill the ES documents from cassandra as described [above](#refill-es-documents-from-cassandra) diff --git a/docs/src/developer/reference/spar-braindump.md b/docs/src/developer/reference/spar-braindump.md index ecb6ccda3ef..24011f54ff5 100644 --- a/docs/src/developer/reference/spar-braindump.md +++ b/docs/src/developer/reference/spar-braindump.md @@ -169,7 +169,7 @@ Effects: and active IdPs. (Internal details: https://github.com/wireapp/wire-team-settings/issues/3465). -```shell +``` curl -v \ -XPOST http://localhost:8080/identity-providers'?replaces='${IDP_ID} \ -H"Z-User: ${ADMIN_ID}" \ @@ -183,7 +183,7 @@ curl -v \ Read the beginning of the last section up to "Option 1". You need `ADMIN_ID` (or `BEARER`) and `IDP_ID`, but not `METADATA_FILE`. -```shell +``` curl -v -XDELETE http://localhost:8080/identity-providers/${IDP_ID} \ -H"Z-User: ${ADMIN_ID}" \ @@ -195,7 +195,7 @@ with this IdP, you will get an error. You can either move these users elsewhere, delete them manually, or purge them implicitly during deletion of the IdP: -```shell +``` curl -v -XDELETE http://localhost:8080/identity-providers/${IDP_ID}?purge=true \ -H"Z-User: ${ADMIN_ID}" \ diff --git a/docs/src/developer/reference/user/activation.md b/docs/src/developer/reference/user/activation.md index 60868cd5811..dbea703730f 100644 --- a/docs/src/developer/reference/user/activation.md +++ b/docs/src/developer/reference/user/activation.md @@ -8,19 +8,22 @@ A user is called _activated_ they have a verified identity -- e.g. a phone numbe A user that has been provisioned via single sign-on is always considered to be activated. -## Activated vs. non-activated users {#RefActivationBenefits} +## Activated vs. non-activated users +(RefActivationBenefits)= Non-activated users can not [connect](connection.md) to others, nor can connection requests be made to anonymous accounts from verified accounts. As a result: * A non-activated user cannot add other users to conversations. The only way to participate in a conversation is to either create a new conversation with link access or to use a link provided by another user. -The only flow where it makes sense for non-activated users to exist is the [wireless flow](registration.md#RefRegistrationWireless) used for [guest rooms](https://wire.com/en/features/encrypted-guest-rooms/) +The only flow where it makes sense for non-activated users to exist is the [wireless flow](RefRegistrationWireless) used for [guest rooms](https://wire.com/en/features/encrypted-guest-rooms/) -## API {#RefActivationApi} +## API +(RefActivationApi)= -### Requesting an activation code {#RefActivationRequest} +### Requesting an activation code +(RefActivationRequest)= -During the [standard registration flow](registration.md#RefRegistrationStandard), the user submits an email address or phone number by making a request to `POST /activate/send`. A six-digit activation code will be sent to that email address / phone number. Sample request and response: +During the [standard registration flow](RefRegistrationStandard), the user submits an email address or phone number by making a request to `POST /activate/send`. A six-digit activation code will be sent to that email address / phone number. Sample request and response: ``` POST /activate/send @@ -39,9 +42,10 @@ The user can submit the activation code during registration to prove that they o The same `POST /activate/send` endpoint can be used to re-request an activation code. Please use this ability sparingly! To avoid unnecessary activation code requests, users should be warned that it might take up to a few minutes for an email or text message to arrive. -### Activating an existing account {#RefActivationSubmit} +### Activating an existing account +(RefActivationSubmit)= -If the account [has not been activated during verification](registration.md#RefRegistrationNoPreverification), it can be activated afterwards by submitting an activation code to `POST /activate`. Sample request and response: +If the account [has not been activated during verification](RefRegistrationNoPreverification), it can be activated afterwards by submitting an activation code to `POST /activate`. Sample request and response: ``` POST /activate @@ -74,20 +78,22 @@ If the email or phone has been verified already, `POST /activate` will return st There is a maximum of 3 activation attempts per activation code. On the third failed attempt the code is invalidated and a new one must be requested. -### Activation event {#RefActivationEvent} +### Activation event +(RefActivationEvent)= When the user becomes activated, they receive an event: -```json +``` { "type": "user.activate", "user": } ``` -### Detecting activation in the self profile {#RefActivationProfile} +### Detecting activation in the self profile +(RefActivationProfile)= -In addition to the [activation event](#RefActivationEvent), activation can be detected by polling the self profile: +In addition to the [activation event](RefActivationEvent), activation can be detected by polling the self profile: ``` GET /self @@ -106,7 +112,8 @@ GET /self If the profile includes `"email"` or `"phone"`, the account is activated. -## Automating activation via email {#RefActivationEmailHeaders} +## Automating activation via email +(RefActivationEmailHeaders)= Our email verification messages contain headers that can be used to automate the activation process. @@ -125,7 +132,8 @@ X-Zeta-Key: ... X-Zeta-Code: 123456 ``` -## Phone/email whitelist {#RefActivationWhitelist} +## Phone/email whitelist +(RefActivationWhitelist)= The backend can be configured to only allow specific phone numbers or email addresses to register. The following options have to be set in `brig.yaml`: diff --git a/docs/src/developer/reference/user/connection.md b/docs/src/developer/reference/user/connection.md index 910c7452881..1f6d9f1f400 100644 --- a/docs/src/developer/reference/user/connection.md +++ b/docs/src/developer/reference/user/connection.md @@ -8,25 +8,29 @@ Two users can be _connected_ or not. If the users are connected, each of them ca By default users with personal accounts are not connected. A user can send another user a _connection request_, which can be ignored or accepted by the other user. A user can also block an existing connection. -Members of the same team are always considered connected, see [Connections between team members](#RefConnectionTeam). +Members of the same team are always considered connected, see [Connections between team members](RefConnectionTeam). -Internally, connection status is a _directed_ edge from one user to another that is attributed with a relation state and some meta information. If a user has a connection to another user, it can be in one of the six [connection states](#RefConnectionStates). +Internally, connection status is a _directed_ edge from one user to another that is attributed with a relation state and some meta information. If a user has a connection to another user, it can be in one of the six [connection states](RefConnectionStates). -## Connection states {#RefConnectionStates} +## Connection states +(RefConnectionStates)= -### Sent {#RefConnectionSent} +### Sent +(RefConnectionSent)= In order for two users to become connected, one of them performs a _connection request_ and the other one accepts it. Initiating a new connection results in a pending 1-1 conversation to be created with the sender as the sole member. When the connection is accepted, the other user joins the conversation. The creator of a new connection (i.e. the sender of the connection request) ends up in this state. From the point of view of the creator, it indicates that a connection request has been sent but not accepted (it might be blocked or ignored). -### Pending {#RefConnectionPending} +### Pending +(RefConnectionPending)= The recipient of a connection request automatically ends up in this state. From his point of view, the state indicates that the connection is pending and awaiting further action (i.e. through accepting, ignoring or blocking it). -### Blocked {#RefConnectionBlocked} +### Blocked +(RefConnectionBlocked)= When a connection is in this state it indicates that the user does not want to be bothered by the other user, e.g. by receiving messages, calls or being added to conversations. @@ -34,27 +38,32 @@ Blocking a user does not prevent receiving further messages of that user in exis When user A blocks user B, the connection restrictions apply to both users -- e.g. A can not add B to conversations, even though it's A who blocked B and not vice-versa. -### Ignored {#RefConnectionIgnored} +### Ignored +(RefConnectionIgnored)= The recipient of a connection request may decide to explicitly "ignore" the request In this state the sender can continue to send further connection attempts. The recipient can change their mind and accept the request later. -### Cancelled {#RefConnectionCancelled} +### Cancelled +(RefConnectionCancelled)= This is a state that the sender can change to if the connection has not yet been accepted. The state will also change for the recipient, unless blocked. -### Accepted {#RefConnectionAccepted} +### Accepted +(RefConnectionAccepted)= A connection in this state is fully accepted by a user. The user thus allows the user at the other end of the connection to add him to conversations. For two users to be considered "connected", both A->B and B->A connections have to be in the "Accepted" state. -## Transitions between connection states {#RefConnectionTransitions} +## Transitions between connection states +(RefConnectionTransitions)= ![Connection state transitions](connection-transitions.png) (To edit this diagram, open [connection-transitions.xml](connection-transitions.xml) with .) -## Connections between team members {#RefConnectionTeam} +## Connections between team members +(RefConnectionTeam)= Users belonging to the same team are always implicitly treated as connected, to make it easier for team members to see each other's profiles, create conversations, etc. diff --git a/docs/src/developer/reference/user/registration.md b/docs/src/developer/reference/user/registration.md index fee8c310227..7ab551cf7c5 100644 --- a/docs/src/developer/reference/user/registration.md +++ b/docs/src/developer/reference/user/registration.md @@ -1,4 +1,5 @@ -# Registration {#RefRegistration} +# Registration +(RefRegistration)= _Authors: Artyom Kazak, Matthias Fischmann_ @@ -6,15 +7,17 @@ _Authors: Artyom Kazak, Matthias Fischmann_ This page describes the "normal" user registration flow. Autoprovisioning is covered separately. -## Summary {#RefRegistrationSummary} +## Summary +(RefRegistrationSummary)= The vast majority of our API is only available to Wire users. Unless a user is autoprovisioned, they have to register an account by calling the `POST /register` endpoint. -Most users also go through [activation](activation.md) -- sharing and verifying an email address and/or phone number with Wire. This can happen either before or after registration. [Certain functionality](activation.md#RefActivationBenefits) is only available to activated users. +Most users also go through [activation](activation.md) -- sharing and verifying an email address and/or phone number with Wire. This can happen either before or after registration. [Certain functionality](RefActivationBenefits) is only available to activated users. -## Standard registration flow {#RefRegistrationStandard} +## Standard registration flow +(RefRegistrationStandard)= -During the standard registration flow, the user first calls [`POST /activate/send`](activation.md#RefActivationRequest) to pre-verify their email address or phone number. Phone numbers must be in [E.164][] format. +During the standard registration flow, the user first calls [`POST /activate/send`](RefActivationRequest) to pre-verify their email address or phone number. Phone numbers must be in [E.164][] format. [E.164]: https://en.wikipedia.org/wiki/E.164 @@ -68,11 +71,12 @@ If the code is incorrect or if an incorrect code has been tried enough times, th } ``` -## Registration without pre-verification {#RefRegistrationNoPreverification} +## Registration without pre-verification +(RefRegistrationNoPreverification)= _NOTE: This flow is currently not used by any clients. At least this was the state on 2020-05-28_ -It is also possible to call `POST /register` without verifying the email address or phone number, in which case the account will have to be activated later by calling [`POST /activate`](activation.md#RefActivationSubmit). Sample API request and response: +It is also possible to call `POST /register` without verifying the email address or phone number, in which case the account will have to be activated later by calling [`POST /activate`](RefActivationSubmit). Sample API request and response: ``` POST /register @@ -107,7 +111,9 @@ Set-Cookie: zuid=... A verification email will be sent to the email address (if provided), and a verification text message will be sent to the phone number (also, if provided). -## Anonymous registration, aka "Wireless" {#RefRegistrationWireless} +## Anonymous registration, aka "Wireless" +(RefRegistrationWireless)= + A user can be created without either email or phone number, in which case only `"name"` is required. The `"name"` does not have to be unique. This feature is used for [guest rooms](https://wire.com/en/features/encrypted-guest-rooms/). diff --git a/docs/src/developer/reference/user/rich-info.md b/docs/src/developer/reference/user/rich-info.md index e6ecb60c297..ec40a2fd599 100644 --- a/docs/src/developer/reference/user/rich-info.md +++ b/docs/src/developer/reference/user/rich-info.md @@ -86,7 +86,7 @@ PUT /scim/v2/Users/:id Here is an example for `PATCH`: -```json +``` PATCH /scim/v2/Users/:id { From 15e240cd30035f3e387a1ff8c84dabf0bb990cd2 Mon Sep 17 00:00:00 2001 From: Arthur Wolf Date: Mon, 22 Aug 2022 18:58:31 +0200 Subject: [PATCH 13/27] fix the no title warning --- docs/src/developer/reference/provisioning/wire_scim_token.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/developer/reference/provisioning/wire_scim_token.md b/docs/src/developer/reference/provisioning/wire_scim_token.md index 62222ed9973..28701d5be20 100644 --- a/docs/src/developer/reference/provisioning/wire_scim_token.md +++ b/docs/src/developer/reference/provisioning/wire_scim_token.md @@ -1,4 +1,4 @@ -Some python code +# Some python code ``` #!/usr/bin/env python3 From 41dcf0aba6a7f63258c44dffa2cb548542141eb7 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 12:54:46 +0200 Subject: [PATCH 14/27] rm images in legacy docs directories. --- docs/developer/architecture/wire-arch-2.png | 1 - docs/developer/architecture/wire-arch-2.xml | 1 - docs/reference/user/connection-transitions.png | 1 - docs/reference/user/connection-transitions.xml | 1 - docs/reference/user/connections-flow-1-backend.png | 1 - 5 files changed, 5 deletions(-) delete mode 100644 docs/developer/architecture/wire-arch-2.png delete mode 100644 docs/developer/architecture/wire-arch-2.xml delete mode 100644 docs/reference/user/connection-transitions.png delete mode 100644 docs/reference/user/connection-transitions.xml delete mode 100644 docs/reference/user/connections-flow-1-backend.png diff --git a/docs/developer/architecture/wire-arch-2.png b/docs/developer/architecture/wire-arch-2.png deleted file mode 100644 index 55b2ed6ab4b..00000000000 --- a/docs/developer/architecture/wire-arch-2.png +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](../legacy/developer/architecture/wire-arch-2.png) diff --git a/docs/developer/architecture/wire-arch-2.xml b/docs/developer/architecture/wire-arch-2.xml deleted file mode 100644 index ace4d60fbcc..00000000000 --- a/docs/developer/architecture/wire-arch-2.xml +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](../legacy/developer/architecture/wire-arch-2.xml) diff --git a/docs/reference/user/connection-transitions.png b/docs/reference/user/connection-transitions.png deleted file mode 100644 index 6722ff359bf..00000000000 --- a/docs/reference/user/connection-transitions.png +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](../legacy/reference/user/connection-transitions.png) diff --git a/docs/reference/user/connection-transitions.xml b/docs/reference/user/connection-transitions.xml deleted file mode 100644 index b78f17675bd..00000000000 --- a/docs/reference/user/connection-transitions.xml +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](../legacy/reference/user/connection-transitions.xml) diff --git a/docs/reference/user/connections-flow-1-backend.png b/docs/reference/user/connections-flow-1-backend.png deleted file mode 100644 index e2166d82f99..00000000000 --- a/docs/reference/user/connections-flow-1-backend.png +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](../legacy/reference/user/connections-flow-1-backend.png) From 104da09c1a19176317ca2d70d672bd5678ca0cc3 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 12:56:09 +0200 Subject: [PATCH 15/27] Update stale file paths in README. --- docs/diagrams/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md index e82e3fe35ab..ed60a1b3ff4 100644 --- a/docs/diagrams/README.md +++ b/docs/diagrams/README.md @@ -1,6 +1,6 @@ # Diagrams with Kroki / Mermaid -This is a "diagrams playground" folder and you don't have to use this. Instead, you can create diagrams in a .rst file inside wire-docs/src with this example kroki/mermaid syntax and use the normal development setup described in wire-docs/README.md to get live previews: +This is a "diagrams playground" folder and you don't have to use this. Instead, you can create diagrams in a .rst file inside ..//src with this example kroki/mermaid syntax and use the normal development setup described in ../README.md to get live previews: ```rst .. kroki:: From 4941ab567233d79fe25667a7231dcb73cc6d4484 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 12:58:01 +0200 Subject: [PATCH 16/27] changelog --- changelog.d/4-docs/publish-developer-docs | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/4-docs/publish-developer-docs diff --git a/changelog.d/4-docs/publish-developer-docs b/changelog.d/4-docs/publish-developer-docs new file mode 100644 index 00000000000..4cd3743cb5f --- /dev/null +++ b/changelog.d/4-docs/publish-developer-docs @@ -0,0 +1 @@ +Move developer docs onto docs.wire.com (instead of exposing them on github only) \ No newline at end of file From 8c07237a35474e4bab9fb4fd102958b26cfacaa4 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 14:29:13 +0200 Subject: [PATCH 17/27] typo --- docs/src/developer/reference/user/registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/developer/reference/user/registration.md b/docs/src/developer/reference/user/registration.md index 7ab551cf7c5..e23e778cc52 100644 --- a/docs/src/developer/reference/user/registration.md +++ b/docs/src/developer/reference/user/registration.md @@ -198,7 +198,7 @@ The rest of the unauthorized end-points is safe: - `~* ^/teams/invitations/info$`: only `GET`; requires invitation code. - `~* ^/teams/invitations/by-email$`: only `HEAD`. - `/invitations/info`: discontinued feature, can be removed from nginz config. -- `/conversations/code-check`: link validatoin for ephemeral/guest users. +- `/conversations/code-check`: link validation for ephemeral/guest users. - `/provider/*`: bots need to be registered to a team before becoming active. so if an attacker does not get access to a team, they cannot deploy a bot. - `~* ^/custom-backend/by-domain/([^/]*)$`: only `GET`; only exposes a list of domains that has is maintained through an internal end-point. used to redirect stock clients from the cloud instance to on-prem instances. - `~* ^/teams/api-docs`: only `GET`; swagger for part of the rest API. safe: it is trivial to identify the software that is running on the instance, and from there it is trivial to get to the source on github, where this can be obtained easily, and more. From ea80bd922a5fdfc83e824ec2a47bf9cb8228633b Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 14:29:18 +0200 Subject: [PATCH 18/27] rm training whitespace. --- docs/src/developer/reference/user/registration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/developer/reference/user/registration.md b/docs/src/developer/reference/user/registration.md index e23e778cc52..6662885bc77 100644 --- a/docs/src/developer/reference/user/registration.md +++ b/docs/src/developer/reference/user/registration.md @@ -1,4 +1,4 @@ -# Registration +# Registration (RefRegistration)= _Authors: Artyom Kazak, Matthias Fischmann_ @@ -7,14 +7,14 @@ _Authors: Artyom Kazak, Matthias Fischmann_ This page describes the "normal" user registration flow. Autoprovisioning is covered separately. -## Summary +## Summary (RefRegistrationSummary)= The vast majority of our API is only available to Wire users. Unless a user is autoprovisioned, they have to register an account by calling the `POST /register` endpoint. Most users also go through [activation](activation.md) -- sharing and verifying an email address and/or phone number with Wire. This can happen either before or after registration. [Certain functionality](RefActivationBenefits) is only available to activated users. -## Standard registration flow +## Standard registration flow (RefRegistrationStandard)= During the standard registration flow, the user first calls [`POST /activate/send`](RefActivationRequest) to pre-verify their email address or phone number. Phone numbers must be in [E.164][] format. @@ -111,7 +111,7 @@ Set-Cookie: zuid=... A verification email will be sent to the email address (if provided), and a verification text message will be sent to the phone number (also, if provided). -## Anonymous registration, aka "Wireless" +## Anonymous registration, aka "Wireless" (RefRegistrationWireless)= From 75af6f050bed3438ab49ecb9307983e00f10958b Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 14:29:29 +0200 Subject: [PATCH 19/27] add legacy developer docs files as references to new docs. --- docs/developer/adding-api-endpoints.md | 1 + docs/developer/adding-config-options.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/developer/adding-api-endpoints.md create mode 100644 docs/developer/adding-config-options.md diff --git a/docs/developer/adding-api-endpoints.md b/docs/developer/adding-api-endpoints.md new file mode 100644 index 00000000000..50b2c985045 --- /dev/null +++ b/docs/developer/adding-api-endpoints.md @@ -0,0 +1 @@ +file has moved [here](??) diff --git a/docs/developer/adding-config-options.md b/docs/developer/adding-config-options.md new file mode 100644 index 00000000000..50b2c985045 --- /dev/null +++ b/docs/developer/adding-config-options.md @@ -0,0 +1 @@ +file has moved [here](??) From 7c1e0ad9a0ef7ed642e517c7b89d8fb56f324f94 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 14:33:42 +0200 Subject: [PATCH 20/27] re-add building.md (resolves merge conflict) --- docs/developer/adding-api-endpoints.md | 2 +- docs/developer/adding-config-options.md | 2 +- docs/developer/building.md | 1 + docs/src/developer/developer/building.md | 84 ++++++++++++++++++++++++ docs/src/developer/index.rst | 1 + 5 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 docs/developer/building.md create mode 100644 docs/src/developer/developer/building.md diff --git a/docs/developer/adding-api-endpoints.md b/docs/developer/adding-api-endpoints.md index 50b2c985045..1ddc661c18f 100644 --- a/docs/developer/adding-api-endpoints.md +++ b/docs/developer/adding-api-endpoints.md @@ -1 +1 @@ -file has moved [here](??) +file has moved [here](../legacy/developer/building.md) diff --git a/docs/developer/adding-config-options.md b/docs/developer/adding-config-options.md index 50b2c985045..1ddc661c18f 100644 --- a/docs/developer/adding-config-options.md +++ b/docs/developer/adding-config-options.md @@ -1 +1 @@ -file has moved [here](??) +file has moved [here](../legacy/developer/building.md) diff --git a/docs/developer/building.md b/docs/developer/building.md new file mode 100644 index 00000000000..1ddc661c18f --- /dev/null +++ b/docs/developer/building.md @@ -0,0 +1 @@ +file has moved [here](../legacy/developer/building.md) diff --git a/docs/src/developer/developer/building.md b/docs/src/developer/developer/building.md new file mode 100644 index 00000000000..edcbe91b78b --- /dev/null +++ b/docs/src/developer/developer/building.md @@ -0,0 +1,84 @@ +# How to build wire-server + +As a prerequisiste install the [nix package manager](https://nixos.org/) and [direnv](https://direnv.net/). + +All following commands expect that you've entered the nix-provided build-environment by running `direnv allow`. + + +1. Create a `.envrc.local` file with these contents + + ``` + export COMPILE_NGINX_USING_NIX=1 + export WIRE_BUILD_WITH_CABAL=1 + ``` + + and reload the direnv via `direnv reload` + +2. Create a `cabal.project.local`. This file is not included in wire-server because it disables optimization. + + ``` + make cabal.project.local + ``` + + This should be re-run whenver a new local cabal package is added to the cabal project. + +Then the following Makefile targets can be used to compile and test wire-server locally: + +``` +# to compile all binaries to ./dist run +make + +# to build and install all of galley's executables +make c package=galley + +# also run galley's unit tests +make c package=galley test=1 +``` + +## Troubleshooting + +### Linker errors while compiling + +Linker errors can occur if the nix-provided build environment (see `nix/` directory) changes. Since cabal is not aware of the changed environment the cached build artifacts in `./dist-newstyle` and `~/.cabal/store/` from previous builds may be invalid causing the linker errors. + +Haskell Language Server stores its build artifacts in `~/.cache/hie-bios` (equivalent to the `./dist-newstyle` directory) which become invalid for the same reason. + +The easiest course of action is to to remove these directories via: + +``` +make full-clean +``` + +# How to run integration tests + +Integration tests require all of the haskell services (brig, galley, cannon, gundeck, proxy, cargohold, spar) to be correctly configured and running, before being able to execute e.g. the `brig-integration` binary. The test for brig also starts nginz, so make sure it has been built before. +These services require most of the deployment dependencies as seen in the architecture diagram to also be available: + +- Required internal dependencies: + - cassandra (with the correct schema) + - elasticsearch (with the correct schema) + - redis +- Required external dependencies are the following configured AWS services (or "fake" replacements providing the same API): + - SES + - SQS + - SNS + - S3 + - DynamoDB +- Required additional software: + - netcat (in order to allow the services being tested to talk to the dependencies above) + +Setting up these real, but in-memory internal and "fake" external dependencies is done easiest using [`docker-compose`](https://docs.docker.com/compose/install/). Run the following in a separate terminal (it will block that terminal, C-c to shut all these docker images down again): + +``` +deploy/dockerephemeral/run.sh +``` + +After all containers are up you can use these Makefile targets to run the tests locally: + +``` +# build and run galley's integration tests +make ci package=galley + +# run galley's integration tests that match a pattern +TASTY_PATTERN="/MLS/" make ci package=galley +``` diff --git a/docs/src/developer/index.rst b/docs/src/developer/index.rst index 44c904a74f4..4eabb97d4cd 100644 --- a/docs/src/developer/index.rst +++ b/docs/src/developer/index.rst @@ -12,6 +12,7 @@ help you. :glob: developer/api-versioning.md <./developer/api-versioning.md> + developer/building.md <./developer/building.md> developer/cassandra-interaction.md <./developer/cassandra-interaction.md> developer/changelog.md <./developer/changelog.md> developer/dependencies.md <./developer/dependencies.md> From d87058e1bb47ea65c214215e9c771c3a9f0e8db5 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 14:37:44 +0200 Subject: [PATCH 21/27] resolve more merge conflicts. --- .../src/developer/reference/config-options.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/src/developer/reference/config-options.md b/docs/src/developer/reference/config-options.md index 03ea91c9eaa..7a5a400e658 100644 --- a/docs/src/developer/reference/config-options.md +++ b/docs/src/developer/reference/config-options.md @@ -26,6 +26,30 @@ Even when the flag is `disabled`, galley will keep writing to the been added in order to deploy new code and backfill data in production. +### MLS private key paths + +The `mlsPrivateKeyPaths` field should contain a mapping from *purposes* and +signature schemes to file paths of corresponding x509 private keys in PEM +format. + +At the moment, the only purpose is `removal`, meaning that the key will be used +to sign external remove proposals. + +For example: + +``` + mlsPrivateKeyPaths: + removal: + ed25519: /etc/secrets/ed25519.pem +``` + +A simple way to generate an ed25519 private key, discarding the corresponding +certificate, is to run the following command: + +``` +openssl req -nodes -newkey ed25519 -keyout ed25519.pem -out /dev/null -subj / +``` + ## Feature flags > Also see [Wire docs](https://docs.wire.com/how-to/install/team-feature-settings.html) where some of the feature flags are documented from an operations point of view. From 100f1ed5b670c0b47b1f781741bde48ff7fccbb3 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 14:48:45 +0200 Subject: [PATCH 22/27] point legacy developer docs files to docs.wire.com --- docs/developer/adding-api-endpoints.md | 2 +- docs/developer/adding-config-options.md | 2 +- docs/developer/api-versioning.md | 2 +- docs/developer/building.md | 2 +- docs/developer/cassandra-interaction.md | 2 +- docs/developer/changelog.md | 2 +- docs/developer/dependencies.md | 2 +- docs/developer/editor-setup.md | 2 +- docs/developer/features.md | 2 +- docs/developer/federation-api-conventions.md | 2 +- docs/developer/how-to.md | 2 +- docs/developer/linting.md | 2 +- docs/developer/processes.md | 2 +- docs/developer/scim/storage.md | 2 +- docs/developer/servant.md | 2 +- docs/developer/testing.md | 2 +- docs/reference/config-options.md | 2 +- docs/reference/conversation.md | 2 +- docs/reference/elastic-search.md | 2 +- docs/reference/elasticsearch-migration-2021-02-16.md | 2 +- docs/reference/make-docker-and-qemu.md | 2 +- docs/reference/provisioning/scim-token.md | 2 +- docs/reference/provisioning/scim-via-curl.md | 2 +- docs/reference/spar-braindump.md | 2 +- docs/reference/user/activation.md | 2 +- docs/reference/user/connection.md | 2 +- docs/reference/user/registration.md | 2 +- docs/reference/user/rich-info.md | 2 +- 28 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/developer/adding-api-endpoints.md b/docs/developer/adding-api-endpoints.md index 1ddc661c18f..f44bcf36d21 100644 --- a/docs/developer/adding-api-endpoints.md +++ b/docs/developer/adding-api-endpoints.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/building.md) +file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/developer/adding-config-options.md b/docs/developer/adding-config-options.md index 1ddc661c18f..f44bcf36d21 100644 --- a/docs/developer/adding-config-options.md +++ b/docs/developer/adding-config-options.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/building.md) +file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/developer/api-versioning.md b/docs/developer/api-versioning.md index 741d4dcc232..8e53dfbe203 100644 --- a/docs/developer/api-versioning.md +++ b/docs/developer/api-versioning.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/api-versioning.md) +file has moved [here](https://docs.wire.com/developer/developer/api-versioning.html) diff --git a/docs/developer/building.md b/docs/developer/building.md index 1ddc661c18f..f44bcf36d21 100644 --- a/docs/developer/building.md +++ b/docs/developer/building.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/building.md) +file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/developer/cassandra-interaction.md b/docs/developer/cassandra-interaction.md index 63af6207cd7..5b331be0719 100644 --- a/docs/developer/cassandra-interaction.md +++ b/docs/developer/cassandra-interaction.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/cassandra-interaction.md) +file has moved [here](https://docs.wire.com/developer/developer/cassandra-interaction.html) diff --git a/docs/developer/changelog.md b/docs/developer/changelog.md index 508079c863b..74482e18f15 100644 --- a/docs/developer/changelog.md +++ b/docs/developer/changelog.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/changelog.md) +file has moved [here](https://docs.wire.com/developer/developer/changelog.html) diff --git a/docs/developer/dependencies.md b/docs/developer/dependencies.md index 392d1d14c90..7844648a60f 100644 --- a/docs/developer/dependencies.md +++ b/docs/developer/dependencies.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/dependencies.md) +file has moved [here](https://docs.wire.com/developer/developer/dependencies.html) diff --git a/docs/developer/editor-setup.md b/docs/developer/editor-setup.md index b3fd30b7ee1..e902ac737fa 100644 --- a/docs/developer/editor-setup.md +++ b/docs/developer/editor-setup.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/editor-setup.md) +file has moved [here](https://docs.wire.com/developer/developer/editor-setup.html) diff --git a/docs/developer/features.md b/docs/developer/features.md index fc5fed6c1fd..7dd2d21c2ee 100644 --- a/docs/developer/features.md +++ b/docs/developer/features.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/features.md) +file has moved [here](https://docs.wire.com/developer/developer/features.html) diff --git a/docs/developer/federation-api-conventions.md b/docs/developer/federation-api-conventions.md index 257a6bae26f..1726c3ba958 100644 --- a/docs/developer/federation-api-conventions.md +++ b/docs/developer/federation-api-conventions.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/federation-api-conventions.md) +file has moved [here](https://docs.wire.com/developer/developer/federation-api-conventions.html) diff --git a/docs/developer/how-to.md b/docs/developer/how-to.md index e9179580fbe..69c7f31c7c8 100644 --- a/docs/developer/how-to.md +++ b/docs/developer/how-to.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/how-to.md) +file has moved [here](https://docs.wire.com/developer/developer/how-to.html) diff --git a/docs/developer/linting.md b/docs/developer/linting.md index 49d740d3c47..ae0de72adea 100644 --- a/docs/developer/linting.md +++ b/docs/developer/linting.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/linting.md) +file has moved [here](https://docs.wire.com/developer/developer/linting.html) diff --git a/docs/developer/processes.md b/docs/developer/processes.md index bda71f73e02..0fb03f67397 100644 --- a/docs/developer/processes.md +++ b/docs/developer/processes.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/processes.md) +file has moved [here](https://docs.wire.com/developer/developer/processes.html) diff --git a/docs/developer/scim/storage.md b/docs/developer/scim/storage.md index a070cdb42f5..05b91485485 100644 --- a/docs/developer/scim/storage.md +++ b/docs/developer/scim/storage.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/scim/storage.md) +file has moved [here](https://docs.wire.com/developer/developer/scim/storage.html) diff --git a/docs/developer/servant.md b/docs/developer/servant.md index de2b8599d52..c1c9c8af23d 100644 --- a/docs/developer/servant.md +++ b/docs/developer/servant.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/servant.md) +file has moved [here](https://docs.wire.com/developer/developer/servant.html) diff --git a/docs/developer/testing.md b/docs/developer/testing.md index ae5e8568bda..0ab3902c172 100644 --- a/docs/developer/testing.md +++ b/docs/developer/testing.md @@ -1 +1 @@ -file has moved [here](../legacy/developer/testing.md) +file has moved [here](https://docs.wire.com/developer/developer/testing.html) diff --git a/docs/reference/config-options.md b/docs/reference/config-options.md index 2a6e342a549..a04556951c5 100644 --- a/docs/reference/config-options.md +++ b/docs/reference/config-options.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/config-options.md) +file has moved [here](https://docs.wire.com/developer/reference/config-options.html) diff --git a/docs/reference/conversation.md b/docs/reference/conversation.md index 23342da490f..897bb5d426c 100644 --- a/docs/reference/conversation.md +++ b/docs/reference/conversation.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/conversation.md) +file has moved [here](https://docs.wire.com/developer/reference/conversation.html) diff --git a/docs/reference/elastic-search.md b/docs/reference/elastic-search.md index fbdf61469b9..84d96dd61de 100644 --- a/docs/reference/elastic-search.md +++ b/docs/reference/elastic-search.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/elastic-search.md) +file has moved [here](https://docs.wire.com/developer/reference/elastic-search.html) diff --git a/docs/reference/elasticsearch-migration-2021-02-16.md b/docs/reference/elasticsearch-migration-2021-02-16.md index 8e17b0b9fdf..f6f895372da 100644 --- a/docs/reference/elasticsearch-migration-2021-02-16.md +++ b/docs/reference/elasticsearch-migration-2021-02-16.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/elasticsearch-migration-2021-02-16.md) +file has moved [here](https://docs.wire.com/developer/reference/elasticsearch-migration-2021-02-16.html) diff --git a/docs/reference/make-docker-and-qemu.md b/docs/reference/make-docker-and-qemu.md index 3c15d68bec0..42bc3decdc8 100644 --- a/docs/reference/make-docker-and-qemu.md +++ b/docs/reference/make-docker-and-qemu.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/make-docker-and-qemu.md) +file has moved [here](https://docs.wire.com/developer/reference/make-docker-and-qemu.html) diff --git a/docs/reference/provisioning/scim-token.md b/docs/reference/provisioning/scim-token.md index b0cf7e2ecbd..99e6c5f963d 100644 --- a/docs/reference/provisioning/scim-token.md +++ b/docs/reference/provisioning/scim-token.md @@ -1 +1 @@ -file has moved [here](../../legacy/reference/provisioning/scim-token.md) +file has moved [here](https://docs.wire.com/developer/reference/provisioning/scim-token.html) diff --git a/docs/reference/provisioning/scim-via-curl.md b/docs/reference/provisioning/scim-via-curl.md index 6eeebaa5438..ea04af09599 100644 --- a/docs/reference/provisioning/scim-via-curl.md +++ b/docs/reference/provisioning/scim-via-curl.md @@ -1 +1 @@ -file has moved [here](../../legacy/reference/provisioning/scim-via-curl.md) +file has moved [here](https://docs.wire.com/developer/reference/provisioning/scim-via-curl.html) diff --git a/docs/reference/spar-braindump.md b/docs/reference/spar-braindump.md index d3e2b1f3ffd..b8e3d27fb99 100644 --- a/docs/reference/spar-braindump.md +++ b/docs/reference/spar-braindump.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/spar-braindump.md) +file has moved [here](https://docs.wire.com/developer/reference/spar-braindump.html) diff --git a/docs/reference/user/activation.md b/docs/reference/user/activation.md index 63bf6c00f1c..72f1ea2fc97 100644 --- a/docs/reference/user/activation.md +++ b/docs/reference/user/activation.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/user/activation.md) +file has moved [here](https://docs.wire.com/developer/reference/user/activation.html) diff --git a/docs/reference/user/connection.md b/docs/reference/user/connection.md index 08c35e1049d..8ab24811404 100644 --- a/docs/reference/user/connection.md +++ b/docs/reference/user/connection.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/user/connection.md) +file has moved [here](https://docs.wire.com/developer/reference/user/connection.html) diff --git a/docs/reference/user/registration.md b/docs/reference/user/registration.md index 1ebf9383d5b..a5147094caf 100644 --- a/docs/reference/user/registration.md +++ b/docs/reference/user/registration.md @@ -1 +1 @@ -file has moved [here](../../legacy/reference/user/registration.md) +file has moved [here](https://docs.wire.com/developer/reference/user/registration.html) diff --git a/docs/reference/user/rich-info.md b/docs/reference/user/rich-info.md index c195e062fe0..0bd8b7be5b9 100644 --- a/docs/reference/user/rich-info.md +++ b/docs/reference/user/rich-info.md @@ -1 +1 @@ -file has moved [here](../legacy/reference/user/rich-info.md) +file has moved [here](https://docs.wire.com/developer/reference/user/rich-info.html) From 47bd601d75bec2e89d8f620d06dbe38a5d18514a Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Wed, 24 Aug 2022 14:53:52 +0200 Subject: [PATCH 23/27] re-add legacy sub-folder --- .../{README.origial.md => README.original.md} | 0 docs/legacy/README.md | 63 +++++++++++++++++++ docs/legacy/developer/adding-api-endpoints.md | 1 + .../legacy/developer/adding-config-options.md | 1 + docs/legacy/developer/api-versioning.md | 1 + docs/legacy/developer/building.md | 1 + .../legacy/developer/cassandra-interaction.md | 1 + docs/legacy/developer/changelog.md | 1 + docs/legacy/developer/convert-to-cabal.md | 1 + docs/legacy/developer/dependencies.md | 1 + docs/legacy/developer/editor-setup.md | 1 + docs/legacy/developer/features.md | 1 + .../developer/federation-api-conventions.md | 1 + docs/legacy/developer/how-to.md | 1 + docs/legacy/developer/linting.md | 1 + docs/legacy/developer/processes.md | 1 + docs/legacy/developer/scim/storage.md | 1 + docs/legacy/developer/servant.md | 1 + docs/legacy/developer/stern.md | 1 + docs/legacy/developer/testing.md | 1 + docs/legacy/reference/cassandra-schema.cql | 1 + docs/legacy/reference/config-options.md | 1 + docs/legacy/reference/conversation.md | 1 + docs/legacy/reference/elastic-search.md | 1 + .../elasticsearch-migration-2021-02-16.md | 1 + docs/legacy/reference/make-docker-and-qemu.md | 1 + .../reference/provisioning/scim-token.md | 1 + .../reference/provisioning/scim-via-curl.md | 1 + .../reference/provisioning/wire_scim_token.py | 1 + docs/legacy/reference/spar-braindump.md | 1 + docs/legacy/reference/user/activation.md | 1 + docs/legacy/reference/user/connection.md | 1 + docs/legacy/reference/user/registration.md | 1 + docs/legacy/reference/user/rich-info.md | 1 + 34 files changed, 95 insertions(+) rename docs/{README.origial.md => README.original.md} (100%) create mode 100644 docs/legacy/README.md create mode 100644 docs/legacy/developer/adding-api-endpoints.md create mode 100644 docs/legacy/developer/adding-config-options.md create mode 100644 docs/legacy/developer/api-versioning.md create mode 100644 docs/legacy/developer/building.md create mode 100644 docs/legacy/developer/cassandra-interaction.md create mode 100644 docs/legacy/developer/changelog.md create mode 120000 docs/legacy/developer/convert-to-cabal.md create mode 100644 docs/legacy/developer/dependencies.md create mode 100644 docs/legacy/developer/editor-setup.md create mode 100644 docs/legacy/developer/features.md create mode 100644 docs/legacy/developer/federation-api-conventions.md create mode 100644 docs/legacy/developer/how-to.md create mode 100644 docs/legacy/developer/linting.md create mode 100644 docs/legacy/developer/processes.md create mode 100644 docs/legacy/developer/scim/storage.md create mode 100644 docs/legacy/developer/servant.md create mode 120000 docs/legacy/developer/stern.md create mode 100644 docs/legacy/developer/testing.md create mode 120000 docs/legacy/reference/cassandra-schema.cql create mode 100644 docs/legacy/reference/config-options.md create mode 100644 docs/legacy/reference/conversation.md create mode 100644 docs/legacy/reference/elastic-search.md create mode 100644 docs/legacy/reference/elasticsearch-migration-2021-02-16.md create mode 100644 docs/legacy/reference/make-docker-and-qemu.md create mode 100644 docs/legacy/reference/provisioning/scim-token.md create mode 100644 docs/legacy/reference/provisioning/scim-via-curl.md create mode 120000 docs/legacy/reference/provisioning/wire_scim_token.py create mode 100644 docs/legacy/reference/spar-braindump.md create mode 100644 docs/legacy/reference/user/activation.md create mode 100644 docs/legacy/reference/user/connection.md create mode 100644 docs/legacy/reference/user/registration.md create mode 100644 docs/legacy/reference/user/rich-info.md diff --git a/docs/README.origial.md b/docs/README.original.md similarity index 100% rename from docs/README.origial.md rename to docs/README.original.md diff --git a/docs/legacy/README.md b/docs/legacy/README.md new file mode 100644 index 00000000000..650b2b0baae --- /dev/null +++ b/docs/legacy/README.md @@ -0,0 +1,63 @@ +# Reference documentation + +What you need to know as a user of the Wire backend: concepts, features, and API. We strive to keep these up to date. + +## Users + +User lifecycle: + +* [User registration](reference/user/registration.md) `{#RefRegistration}` +* [User activation](reference/user/activation.md) `{#RefActivation}` + +User profiles and metadata: + +* [Connections between users](reference/user/connection.md) `{#RefConnection}` +* [Rich info](reference/user/rich-info.md) `{#RefRichInfo}` + +TODO. + +## Teams + +TODO. + +## Messaging + +TODO. + +## Single sign-on + +TODO. + +## SCIM provisioning + +We have support for provisioning users via SCIM ([RFC 7664][], [RFC 7643][]). It's in the beta stage. + +[RFC 7664]: https://tools.ietf.org/html/rfc7664 +[RFC 7643]: https://tools.ietf.org/html/rfc7643 + +* [Using the SCIM API with curl](reference/provisioning/scim-via-curl.md) `{#RefScimViaCurl}` +* [Authentication via SCIM tokens](reference/provisioning/scim-token.md) `{#RefScimToken}` + +# Developer documentation + +Internal documentation detailing what you need to know as a Wire backend developer. All of these documents can and should be referenced in the code. + +If you're not a member of the Wire backend team, you might still find these documents useful, but keep in mind that they are a work in progress. + +* [Development setup](developer/dependencies.md) `{#DevDeps}` +* [Editor setup](developer/editor-setup.md) `{#DevEditor}` +* [Storing SCIM-related data](developer/scim/storage.md) `{#DevScimStorage}` +* TODO + +## Cassandra + +We use [Cassandra](http://cassandra.apache.org/) as the primary data store. It is scalable, has very fast reads and writes, and is conceptually simple (or at least simpler than SQL databases). + +Some helpful links: + +* [Query syntax](https://docs.datastax.com/en/cql/3.3/cql/cql_reference/cqlReferenceTOC.html) + +* How deletes work in Cassandra: + + - [Understanding Deletes](https://medium.com/@foundev/domain-modeling-around-deletes-1cc9b6da0d24) + - [Cassandra Compaction and Tombstone Behavior](http://engblog.polyvore.com/2015/03/cassandra-compaction-and-tombstone.html) diff --git a/docs/legacy/developer/adding-api-endpoints.md b/docs/legacy/developer/adding-api-endpoints.md new file mode 100644 index 00000000000..f44bcf36d21 --- /dev/null +++ b/docs/legacy/developer/adding-api-endpoints.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/legacy/developer/adding-config-options.md b/docs/legacy/developer/adding-config-options.md new file mode 100644 index 00000000000..f44bcf36d21 --- /dev/null +++ b/docs/legacy/developer/adding-config-options.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/legacy/developer/api-versioning.md b/docs/legacy/developer/api-versioning.md new file mode 100644 index 00000000000..8e53dfbe203 --- /dev/null +++ b/docs/legacy/developer/api-versioning.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/api-versioning.html) diff --git a/docs/legacy/developer/building.md b/docs/legacy/developer/building.md new file mode 100644 index 00000000000..f44bcf36d21 --- /dev/null +++ b/docs/legacy/developer/building.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/legacy/developer/cassandra-interaction.md b/docs/legacy/developer/cassandra-interaction.md new file mode 100644 index 00000000000..5b331be0719 --- /dev/null +++ b/docs/legacy/developer/cassandra-interaction.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/cassandra-interaction.html) diff --git a/docs/legacy/developer/changelog.md b/docs/legacy/developer/changelog.md new file mode 100644 index 00000000000..74482e18f15 --- /dev/null +++ b/docs/legacy/developer/changelog.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/changelog.html) diff --git a/docs/legacy/developer/convert-to-cabal.md b/docs/legacy/developer/convert-to-cabal.md new file mode 120000 index 00000000000..05eb4322d55 --- /dev/null +++ b/docs/legacy/developer/convert-to-cabal.md @@ -0,0 +1 @@ +../../tools/convert-to-cabal/README.md \ No newline at end of file diff --git a/docs/legacy/developer/dependencies.md b/docs/legacy/developer/dependencies.md new file mode 100644 index 00000000000..7844648a60f --- /dev/null +++ b/docs/legacy/developer/dependencies.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/dependencies.html) diff --git a/docs/legacy/developer/editor-setup.md b/docs/legacy/developer/editor-setup.md new file mode 100644 index 00000000000..e902ac737fa --- /dev/null +++ b/docs/legacy/developer/editor-setup.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/editor-setup.html) diff --git a/docs/legacy/developer/features.md b/docs/legacy/developer/features.md new file mode 100644 index 00000000000..7dd2d21c2ee --- /dev/null +++ b/docs/legacy/developer/features.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/features.html) diff --git a/docs/legacy/developer/federation-api-conventions.md b/docs/legacy/developer/federation-api-conventions.md new file mode 100644 index 00000000000..1726c3ba958 --- /dev/null +++ b/docs/legacy/developer/federation-api-conventions.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/federation-api-conventions.html) diff --git a/docs/legacy/developer/how-to.md b/docs/legacy/developer/how-to.md new file mode 100644 index 00000000000..69c7f31c7c8 --- /dev/null +++ b/docs/legacy/developer/how-to.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/how-to.html) diff --git a/docs/legacy/developer/linting.md b/docs/legacy/developer/linting.md new file mode 100644 index 00000000000..ae0de72adea --- /dev/null +++ b/docs/legacy/developer/linting.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/linting.html) diff --git a/docs/legacy/developer/processes.md b/docs/legacy/developer/processes.md new file mode 100644 index 00000000000..0fb03f67397 --- /dev/null +++ b/docs/legacy/developer/processes.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/processes.html) diff --git a/docs/legacy/developer/scim/storage.md b/docs/legacy/developer/scim/storage.md new file mode 100644 index 00000000000..05b91485485 --- /dev/null +++ b/docs/legacy/developer/scim/storage.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/scim/storage.html) diff --git a/docs/legacy/developer/servant.md b/docs/legacy/developer/servant.md new file mode 100644 index 00000000000..c1c9c8af23d --- /dev/null +++ b/docs/legacy/developer/servant.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/servant.html) diff --git a/docs/legacy/developer/stern.md b/docs/legacy/developer/stern.md new file mode 120000 index 00000000000..f1a37ac1b5f --- /dev/null +++ b/docs/legacy/developer/stern.md @@ -0,0 +1 @@ +../../tools/stern/README.md \ No newline at end of file diff --git a/docs/legacy/developer/testing.md b/docs/legacy/developer/testing.md new file mode 100644 index 00000000000..0ab3902c172 --- /dev/null +++ b/docs/legacy/developer/testing.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/developer/testing.html) diff --git a/docs/legacy/reference/cassandra-schema.cql b/docs/legacy/reference/cassandra-schema.cql new file mode 120000 index 00000000000..77e9ef36a84 --- /dev/null +++ b/docs/legacy/reference/cassandra-schema.cql @@ -0,0 +1 @@ +../../cassandra-schema.cql \ No newline at end of file diff --git a/docs/legacy/reference/config-options.md b/docs/legacy/reference/config-options.md new file mode 100644 index 00000000000..a04556951c5 --- /dev/null +++ b/docs/legacy/reference/config-options.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/config-options.html) diff --git a/docs/legacy/reference/conversation.md b/docs/legacy/reference/conversation.md new file mode 100644 index 00000000000..897bb5d426c --- /dev/null +++ b/docs/legacy/reference/conversation.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/conversation.html) diff --git a/docs/legacy/reference/elastic-search.md b/docs/legacy/reference/elastic-search.md new file mode 100644 index 00000000000..84d96dd61de --- /dev/null +++ b/docs/legacy/reference/elastic-search.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/elastic-search.html) diff --git a/docs/legacy/reference/elasticsearch-migration-2021-02-16.md b/docs/legacy/reference/elasticsearch-migration-2021-02-16.md new file mode 100644 index 00000000000..f6f895372da --- /dev/null +++ b/docs/legacy/reference/elasticsearch-migration-2021-02-16.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/elasticsearch-migration-2021-02-16.html) diff --git a/docs/legacy/reference/make-docker-and-qemu.md b/docs/legacy/reference/make-docker-and-qemu.md new file mode 100644 index 00000000000..42bc3decdc8 --- /dev/null +++ b/docs/legacy/reference/make-docker-and-qemu.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/make-docker-and-qemu.html) diff --git a/docs/legacy/reference/provisioning/scim-token.md b/docs/legacy/reference/provisioning/scim-token.md new file mode 100644 index 00000000000..99e6c5f963d --- /dev/null +++ b/docs/legacy/reference/provisioning/scim-token.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/provisioning/scim-token.html) diff --git a/docs/legacy/reference/provisioning/scim-via-curl.md b/docs/legacy/reference/provisioning/scim-via-curl.md new file mode 100644 index 00000000000..ea04af09599 --- /dev/null +++ b/docs/legacy/reference/provisioning/scim-via-curl.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/provisioning/scim-via-curl.html) diff --git a/docs/legacy/reference/provisioning/wire_scim_token.py b/docs/legacy/reference/provisioning/wire_scim_token.py new file mode 120000 index 00000000000..7be5401a613 --- /dev/null +++ b/docs/legacy/reference/provisioning/wire_scim_token.py @@ -0,0 +1 @@ +../../legacy/reference/provisioning/wire_scim_token.py \ No newline at end of file diff --git a/docs/legacy/reference/spar-braindump.md b/docs/legacy/reference/spar-braindump.md new file mode 100644 index 00000000000..b8e3d27fb99 --- /dev/null +++ b/docs/legacy/reference/spar-braindump.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/spar-braindump.html) diff --git a/docs/legacy/reference/user/activation.md b/docs/legacy/reference/user/activation.md new file mode 100644 index 00000000000..72f1ea2fc97 --- /dev/null +++ b/docs/legacy/reference/user/activation.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/user/activation.html) diff --git a/docs/legacy/reference/user/connection.md b/docs/legacy/reference/user/connection.md new file mode 100644 index 00000000000..8ab24811404 --- /dev/null +++ b/docs/legacy/reference/user/connection.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/user/connection.html) diff --git a/docs/legacy/reference/user/registration.md b/docs/legacy/reference/user/registration.md new file mode 100644 index 00000000000..a5147094caf --- /dev/null +++ b/docs/legacy/reference/user/registration.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/user/registration.html) diff --git a/docs/legacy/reference/user/rich-info.md b/docs/legacy/reference/user/rich-info.md new file mode 100644 index 00000000000..0bd8b7be5b9 --- /dev/null +++ b/docs/legacy/reference/user/rich-info.md @@ -0,0 +1 @@ +file has moved [here](https://docs.wire.com/developer/reference/user/rich-info.html) From 430b29db8d83a6554d4b69045ec087ba7a0e140d Mon Sep 17 00:00:00 2001 From: Stefan Matting Date: Wed, 24 Aug 2022 16:29:13 +0200 Subject: [PATCH 24/27] remove tombstones --- docs/developer/adding-api-endpoints.md | 1 - docs/developer/adding-config-options.md | 1 - docs/developer/api-versioning.md | 1 - docs/developer/building.md | 1 - docs/developer/cassandra-interaction.md | 1 - docs/developer/changelog.md | 1 - docs/developer/convert-to-cabal.md | 1 - docs/developer/dependencies.md | 1 - docs/developer/editor-setup.md | 1 - docs/developer/features.md | 1 - docs/developer/federation-api-conventions.md | 1 - docs/developer/how-to.md | 1 - docs/developer/linting.md | 1 - docs/developer/processes.md | 1 - docs/developer/scim/storage.md | 1 - docs/developer/servant.md | 1 - docs/developer/stern.md | 1 - docs/developer/testing.md | 1 - docs/legacy/README.md | 63 ------------------- docs/legacy/developer/adding-api-endpoints.md | 1 - .../legacy/developer/adding-config-options.md | 1 - docs/legacy/developer/api-versioning.md | 1 - docs/legacy/developer/building.md | 1 - .../legacy/developer/cassandra-interaction.md | 1 - docs/legacy/developer/changelog.md | 1 - docs/legacy/developer/convert-to-cabal.md | 1 - docs/legacy/developer/dependencies.md | 1 - docs/legacy/developer/editor-setup.md | 1 - docs/legacy/developer/features.md | 1 - .../developer/federation-api-conventions.md | 1 - docs/legacy/developer/how-to.md | 1 - docs/legacy/developer/linting.md | 1 - docs/legacy/developer/processes.md | 1 - docs/legacy/developer/scim/storage.md | 1 - docs/legacy/developer/servant.md | 1 - docs/legacy/developer/stern.md | 1 - docs/legacy/developer/testing.md | 1 - docs/legacy/reference/cassandra-schema.cql | 1 - docs/legacy/reference/config-options.md | 1 - docs/legacy/reference/conversation.md | 1 - docs/legacy/reference/elastic-search.md | 1 - .../elasticsearch-migration-2021-02-16.md | 1 - docs/legacy/reference/make-docker-and-qemu.md | 1 - .../reference/provisioning/scim-token.md | 1 - .../reference/provisioning/scim-via-curl.md | 1 - .../reference/provisioning/wire_scim_token.py | 1 - docs/legacy/reference/spar-braindump.md | 1 - docs/legacy/reference/user/activation.md | 1 - docs/legacy/reference/user/connection.md | 1 - docs/legacy/reference/user/registration.md | 1 - docs/legacy/reference/user/rich-info.md | 1 - docs/reference/cassandra-schema.cql | 1 - docs/reference/config-options.md | 1 - docs/reference/conversation.md | 1 - docs/reference/elastic-search.md | 1 - .../elasticsearch-migration-2021-02-16.md | 1 - docs/reference/make-docker-and-qemu.md | 1 - docs/reference/provisioning/scim-token.md | 1 - docs/reference/provisioning/scim-via-curl.md | 1 - .../reference/provisioning/wire_scim_token.py | 1 - docs/reference/spar-braindump.md | 1 - docs/reference/user/activation.md | 1 - docs/reference/user/connection.md | 1 - docs/reference/user/registration.md | 1 - docs/reference/user/rich-info.md | 1 - .../reference/provisioning/scim-via-curl.md | 1 - .../src/developer/reference/spar-braindump.md | 3 +- 67 files changed, 1 insertion(+), 130 deletions(-) delete mode 100644 docs/developer/adding-api-endpoints.md delete mode 100644 docs/developer/adding-config-options.md delete mode 100644 docs/developer/api-versioning.md delete mode 100644 docs/developer/building.md delete mode 100644 docs/developer/cassandra-interaction.md delete mode 100644 docs/developer/changelog.md delete mode 120000 docs/developer/convert-to-cabal.md delete mode 100644 docs/developer/dependencies.md delete mode 100644 docs/developer/editor-setup.md delete mode 100644 docs/developer/features.md delete mode 100644 docs/developer/federation-api-conventions.md delete mode 100644 docs/developer/how-to.md delete mode 100644 docs/developer/linting.md delete mode 100644 docs/developer/processes.md delete mode 100644 docs/developer/scim/storage.md delete mode 100644 docs/developer/servant.md delete mode 120000 docs/developer/stern.md delete mode 100644 docs/developer/testing.md delete mode 100644 docs/legacy/README.md delete mode 100644 docs/legacy/developer/adding-api-endpoints.md delete mode 100644 docs/legacy/developer/adding-config-options.md delete mode 100644 docs/legacy/developer/api-versioning.md delete mode 100644 docs/legacy/developer/building.md delete mode 100644 docs/legacy/developer/cassandra-interaction.md delete mode 100644 docs/legacy/developer/changelog.md delete mode 120000 docs/legacy/developer/convert-to-cabal.md delete mode 100644 docs/legacy/developer/dependencies.md delete mode 100644 docs/legacy/developer/editor-setup.md delete mode 100644 docs/legacy/developer/features.md delete mode 100644 docs/legacy/developer/federation-api-conventions.md delete mode 100644 docs/legacy/developer/how-to.md delete mode 100644 docs/legacy/developer/linting.md delete mode 100644 docs/legacy/developer/processes.md delete mode 100644 docs/legacy/developer/scim/storage.md delete mode 100644 docs/legacy/developer/servant.md delete mode 120000 docs/legacy/developer/stern.md delete mode 100644 docs/legacy/developer/testing.md delete mode 120000 docs/legacy/reference/cassandra-schema.cql delete mode 100644 docs/legacy/reference/config-options.md delete mode 100644 docs/legacy/reference/conversation.md delete mode 100644 docs/legacy/reference/elastic-search.md delete mode 100644 docs/legacy/reference/elasticsearch-migration-2021-02-16.md delete mode 100644 docs/legacy/reference/make-docker-and-qemu.md delete mode 100644 docs/legacy/reference/provisioning/scim-token.md delete mode 100644 docs/legacy/reference/provisioning/scim-via-curl.md delete mode 120000 docs/legacy/reference/provisioning/wire_scim_token.py delete mode 100644 docs/legacy/reference/spar-braindump.md delete mode 100644 docs/legacy/reference/user/activation.md delete mode 100644 docs/legacy/reference/user/connection.md delete mode 100644 docs/legacy/reference/user/registration.md delete mode 100644 docs/legacy/reference/user/rich-info.md delete mode 120000 docs/reference/cassandra-schema.cql delete mode 100644 docs/reference/config-options.md delete mode 100644 docs/reference/conversation.md delete mode 100644 docs/reference/elastic-search.md delete mode 100644 docs/reference/elasticsearch-migration-2021-02-16.md delete mode 100644 docs/reference/make-docker-and-qemu.md delete mode 100644 docs/reference/provisioning/scim-token.md delete mode 100644 docs/reference/provisioning/scim-via-curl.md delete mode 120000 docs/reference/provisioning/wire_scim_token.py delete mode 100644 docs/reference/spar-braindump.md delete mode 100644 docs/reference/user/activation.md delete mode 100644 docs/reference/user/connection.md delete mode 100644 docs/reference/user/registration.md delete mode 100644 docs/reference/user/rich-info.md delete mode 100644 docs/src/developer/reference/provisioning/scim-via-curl.md diff --git a/docs/developer/adding-api-endpoints.md b/docs/developer/adding-api-endpoints.md deleted file mode 100644 index f44bcf36d21..00000000000 --- a/docs/developer/adding-api-endpoints.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/developer/adding-config-options.md b/docs/developer/adding-config-options.md deleted file mode 100644 index f44bcf36d21..00000000000 --- a/docs/developer/adding-config-options.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/developer/api-versioning.md b/docs/developer/api-versioning.md deleted file mode 100644 index 8e53dfbe203..00000000000 --- a/docs/developer/api-versioning.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/api-versioning.html) diff --git a/docs/developer/building.md b/docs/developer/building.md deleted file mode 100644 index f44bcf36d21..00000000000 --- a/docs/developer/building.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/developer/cassandra-interaction.md b/docs/developer/cassandra-interaction.md deleted file mode 100644 index 5b331be0719..00000000000 --- a/docs/developer/cassandra-interaction.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/cassandra-interaction.html) diff --git a/docs/developer/changelog.md b/docs/developer/changelog.md deleted file mode 100644 index 74482e18f15..00000000000 --- a/docs/developer/changelog.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/changelog.html) diff --git a/docs/developer/convert-to-cabal.md b/docs/developer/convert-to-cabal.md deleted file mode 120000 index 05eb4322d55..00000000000 --- a/docs/developer/convert-to-cabal.md +++ /dev/null @@ -1 +0,0 @@ -../../tools/convert-to-cabal/README.md \ No newline at end of file diff --git a/docs/developer/dependencies.md b/docs/developer/dependencies.md deleted file mode 100644 index 7844648a60f..00000000000 --- a/docs/developer/dependencies.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/dependencies.html) diff --git a/docs/developer/editor-setup.md b/docs/developer/editor-setup.md deleted file mode 100644 index e902ac737fa..00000000000 --- a/docs/developer/editor-setup.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/editor-setup.html) diff --git a/docs/developer/features.md b/docs/developer/features.md deleted file mode 100644 index 7dd2d21c2ee..00000000000 --- a/docs/developer/features.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/features.html) diff --git a/docs/developer/federation-api-conventions.md b/docs/developer/federation-api-conventions.md deleted file mode 100644 index 1726c3ba958..00000000000 --- a/docs/developer/federation-api-conventions.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/federation-api-conventions.html) diff --git a/docs/developer/how-to.md b/docs/developer/how-to.md deleted file mode 100644 index 69c7f31c7c8..00000000000 --- a/docs/developer/how-to.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/how-to.html) diff --git a/docs/developer/linting.md b/docs/developer/linting.md deleted file mode 100644 index ae0de72adea..00000000000 --- a/docs/developer/linting.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/linting.html) diff --git a/docs/developer/processes.md b/docs/developer/processes.md deleted file mode 100644 index 0fb03f67397..00000000000 --- a/docs/developer/processes.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/processes.html) diff --git a/docs/developer/scim/storage.md b/docs/developer/scim/storage.md deleted file mode 100644 index 05b91485485..00000000000 --- a/docs/developer/scim/storage.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/scim/storage.html) diff --git a/docs/developer/servant.md b/docs/developer/servant.md deleted file mode 100644 index c1c9c8af23d..00000000000 --- a/docs/developer/servant.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/servant.html) diff --git a/docs/developer/stern.md b/docs/developer/stern.md deleted file mode 120000 index f1a37ac1b5f..00000000000 --- a/docs/developer/stern.md +++ /dev/null @@ -1 +0,0 @@ -../../tools/stern/README.md \ No newline at end of file diff --git a/docs/developer/testing.md b/docs/developer/testing.md deleted file mode 100644 index 0ab3902c172..00000000000 --- a/docs/developer/testing.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/testing.html) diff --git a/docs/legacy/README.md b/docs/legacy/README.md deleted file mode 100644 index 650b2b0baae..00000000000 --- a/docs/legacy/README.md +++ /dev/null @@ -1,63 +0,0 @@ -# Reference documentation - -What you need to know as a user of the Wire backend: concepts, features, and API. We strive to keep these up to date. - -## Users - -User lifecycle: - -* [User registration](reference/user/registration.md) `{#RefRegistration}` -* [User activation](reference/user/activation.md) `{#RefActivation}` - -User profiles and metadata: - -* [Connections between users](reference/user/connection.md) `{#RefConnection}` -* [Rich info](reference/user/rich-info.md) `{#RefRichInfo}` - -TODO. - -## Teams - -TODO. - -## Messaging - -TODO. - -## Single sign-on - -TODO. - -## SCIM provisioning - -We have support for provisioning users via SCIM ([RFC 7664][], [RFC 7643][]). It's in the beta stage. - -[RFC 7664]: https://tools.ietf.org/html/rfc7664 -[RFC 7643]: https://tools.ietf.org/html/rfc7643 - -* [Using the SCIM API with curl](reference/provisioning/scim-via-curl.md) `{#RefScimViaCurl}` -* [Authentication via SCIM tokens](reference/provisioning/scim-token.md) `{#RefScimToken}` - -# Developer documentation - -Internal documentation detailing what you need to know as a Wire backend developer. All of these documents can and should be referenced in the code. - -If you're not a member of the Wire backend team, you might still find these documents useful, but keep in mind that they are a work in progress. - -* [Development setup](developer/dependencies.md) `{#DevDeps}` -* [Editor setup](developer/editor-setup.md) `{#DevEditor}` -* [Storing SCIM-related data](developer/scim/storage.md) `{#DevScimStorage}` -* TODO - -## Cassandra - -We use [Cassandra](http://cassandra.apache.org/) as the primary data store. It is scalable, has very fast reads and writes, and is conceptually simple (or at least simpler than SQL databases). - -Some helpful links: - -* [Query syntax](https://docs.datastax.com/en/cql/3.3/cql/cql_reference/cqlReferenceTOC.html) - -* How deletes work in Cassandra: - - - [Understanding Deletes](https://medium.com/@foundev/domain-modeling-around-deletes-1cc9b6da0d24) - - [Cassandra Compaction and Tombstone Behavior](http://engblog.polyvore.com/2015/03/cassandra-compaction-and-tombstone.html) diff --git a/docs/legacy/developer/adding-api-endpoints.md b/docs/legacy/developer/adding-api-endpoints.md deleted file mode 100644 index f44bcf36d21..00000000000 --- a/docs/legacy/developer/adding-api-endpoints.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/legacy/developer/adding-config-options.md b/docs/legacy/developer/adding-config-options.md deleted file mode 100644 index f44bcf36d21..00000000000 --- a/docs/legacy/developer/adding-config-options.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/legacy/developer/api-versioning.md b/docs/legacy/developer/api-versioning.md deleted file mode 100644 index 8e53dfbe203..00000000000 --- a/docs/legacy/developer/api-versioning.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/api-versioning.html) diff --git a/docs/legacy/developer/building.md b/docs/legacy/developer/building.md deleted file mode 100644 index f44bcf36d21..00000000000 --- a/docs/legacy/developer/building.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/building.html) diff --git a/docs/legacy/developer/cassandra-interaction.md b/docs/legacy/developer/cassandra-interaction.md deleted file mode 100644 index 5b331be0719..00000000000 --- a/docs/legacy/developer/cassandra-interaction.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/cassandra-interaction.html) diff --git a/docs/legacy/developer/changelog.md b/docs/legacy/developer/changelog.md deleted file mode 100644 index 74482e18f15..00000000000 --- a/docs/legacy/developer/changelog.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/changelog.html) diff --git a/docs/legacy/developer/convert-to-cabal.md b/docs/legacy/developer/convert-to-cabal.md deleted file mode 120000 index 05eb4322d55..00000000000 --- a/docs/legacy/developer/convert-to-cabal.md +++ /dev/null @@ -1 +0,0 @@ -../../tools/convert-to-cabal/README.md \ No newline at end of file diff --git a/docs/legacy/developer/dependencies.md b/docs/legacy/developer/dependencies.md deleted file mode 100644 index 7844648a60f..00000000000 --- a/docs/legacy/developer/dependencies.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/dependencies.html) diff --git a/docs/legacy/developer/editor-setup.md b/docs/legacy/developer/editor-setup.md deleted file mode 100644 index e902ac737fa..00000000000 --- a/docs/legacy/developer/editor-setup.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/editor-setup.html) diff --git a/docs/legacy/developer/features.md b/docs/legacy/developer/features.md deleted file mode 100644 index 7dd2d21c2ee..00000000000 --- a/docs/legacy/developer/features.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/features.html) diff --git a/docs/legacy/developer/federation-api-conventions.md b/docs/legacy/developer/federation-api-conventions.md deleted file mode 100644 index 1726c3ba958..00000000000 --- a/docs/legacy/developer/federation-api-conventions.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/federation-api-conventions.html) diff --git a/docs/legacy/developer/how-to.md b/docs/legacy/developer/how-to.md deleted file mode 100644 index 69c7f31c7c8..00000000000 --- a/docs/legacy/developer/how-to.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/how-to.html) diff --git a/docs/legacy/developer/linting.md b/docs/legacy/developer/linting.md deleted file mode 100644 index ae0de72adea..00000000000 --- a/docs/legacy/developer/linting.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/linting.html) diff --git a/docs/legacy/developer/processes.md b/docs/legacy/developer/processes.md deleted file mode 100644 index 0fb03f67397..00000000000 --- a/docs/legacy/developer/processes.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/processes.html) diff --git a/docs/legacy/developer/scim/storage.md b/docs/legacy/developer/scim/storage.md deleted file mode 100644 index 05b91485485..00000000000 --- a/docs/legacy/developer/scim/storage.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/scim/storage.html) diff --git a/docs/legacy/developer/servant.md b/docs/legacy/developer/servant.md deleted file mode 100644 index c1c9c8af23d..00000000000 --- a/docs/legacy/developer/servant.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/servant.html) diff --git a/docs/legacy/developer/stern.md b/docs/legacy/developer/stern.md deleted file mode 120000 index f1a37ac1b5f..00000000000 --- a/docs/legacy/developer/stern.md +++ /dev/null @@ -1 +0,0 @@ -../../tools/stern/README.md \ No newline at end of file diff --git a/docs/legacy/developer/testing.md b/docs/legacy/developer/testing.md deleted file mode 100644 index 0ab3902c172..00000000000 --- a/docs/legacy/developer/testing.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/developer/testing.html) diff --git a/docs/legacy/reference/cassandra-schema.cql b/docs/legacy/reference/cassandra-schema.cql deleted file mode 120000 index 77e9ef36a84..00000000000 --- a/docs/legacy/reference/cassandra-schema.cql +++ /dev/null @@ -1 +0,0 @@ -../../cassandra-schema.cql \ No newline at end of file diff --git a/docs/legacy/reference/config-options.md b/docs/legacy/reference/config-options.md deleted file mode 100644 index a04556951c5..00000000000 --- a/docs/legacy/reference/config-options.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/config-options.html) diff --git a/docs/legacy/reference/conversation.md b/docs/legacy/reference/conversation.md deleted file mode 100644 index 897bb5d426c..00000000000 --- a/docs/legacy/reference/conversation.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/conversation.html) diff --git a/docs/legacy/reference/elastic-search.md b/docs/legacy/reference/elastic-search.md deleted file mode 100644 index 84d96dd61de..00000000000 --- a/docs/legacy/reference/elastic-search.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/elastic-search.html) diff --git a/docs/legacy/reference/elasticsearch-migration-2021-02-16.md b/docs/legacy/reference/elasticsearch-migration-2021-02-16.md deleted file mode 100644 index f6f895372da..00000000000 --- a/docs/legacy/reference/elasticsearch-migration-2021-02-16.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/elasticsearch-migration-2021-02-16.html) diff --git a/docs/legacy/reference/make-docker-and-qemu.md b/docs/legacy/reference/make-docker-and-qemu.md deleted file mode 100644 index 42bc3decdc8..00000000000 --- a/docs/legacy/reference/make-docker-and-qemu.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/make-docker-and-qemu.html) diff --git a/docs/legacy/reference/provisioning/scim-token.md b/docs/legacy/reference/provisioning/scim-token.md deleted file mode 100644 index 99e6c5f963d..00000000000 --- a/docs/legacy/reference/provisioning/scim-token.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/provisioning/scim-token.html) diff --git a/docs/legacy/reference/provisioning/scim-via-curl.md b/docs/legacy/reference/provisioning/scim-via-curl.md deleted file mode 100644 index ea04af09599..00000000000 --- a/docs/legacy/reference/provisioning/scim-via-curl.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/provisioning/scim-via-curl.html) diff --git a/docs/legacy/reference/provisioning/wire_scim_token.py b/docs/legacy/reference/provisioning/wire_scim_token.py deleted file mode 120000 index 7be5401a613..00000000000 --- a/docs/legacy/reference/provisioning/wire_scim_token.py +++ /dev/null @@ -1 +0,0 @@ -../../legacy/reference/provisioning/wire_scim_token.py \ No newline at end of file diff --git a/docs/legacy/reference/spar-braindump.md b/docs/legacy/reference/spar-braindump.md deleted file mode 100644 index b8e3d27fb99..00000000000 --- a/docs/legacy/reference/spar-braindump.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/spar-braindump.html) diff --git a/docs/legacy/reference/user/activation.md b/docs/legacy/reference/user/activation.md deleted file mode 100644 index 72f1ea2fc97..00000000000 --- a/docs/legacy/reference/user/activation.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/user/activation.html) diff --git a/docs/legacy/reference/user/connection.md b/docs/legacy/reference/user/connection.md deleted file mode 100644 index 8ab24811404..00000000000 --- a/docs/legacy/reference/user/connection.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/user/connection.html) diff --git a/docs/legacy/reference/user/registration.md b/docs/legacy/reference/user/registration.md deleted file mode 100644 index a5147094caf..00000000000 --- a/docs/legacy/reference/user/registration.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/user/registration.html) diff --git a/docs/legacy/reference/user/rich-info.md b/docs/legacy/reference/user/rich-info.md deleted file mode 100644 index 0bd8b7be5b9..00000000000 --- a/docs/legacy/reference/user/rich-info.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/user/rich-info.html) diff --git a/docs/reference/cassandra-schema.cql b/docs/reference/cassandra-schema.cql deleted file mode 120000 index 77e9ef36a84..00000000000 --- a/docs/reference/cassandra-schema.cql +++ /dev/null @@ -1 +0,0 @@ -../../cassandra-schema.cql \ No newline at end of file diff --git a/docs/reference/config-options.md b/docs/reference/config-options.md deleted file mode 100644 index a04556951c5..00000000000 --- a/docs/reference/config-options.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/config-options.html) diff --git a/docs/reference/conversation.md b/docs/reference/conversation.md deleted file mode 100644 index 897bb5d426c..00000000000 --- a/docs/reference/conversation.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/conversation.html) diff --git a/docs/reference/elastic-search.md b/docs/reference/elastic-search.md deleted file mode 100644 index 84d96dd61de..00000000000 --- a/docs/reference/elastic-search.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/elastic-search.html) diff --git a/docs/reference/elasticsearch-migration-2021-02-16.md b/docs/reference/elasticsearch-migration-2021-02-16.md deleted file mode 100644 index f6f895372da..00000000000 --- a/docs/reference/elasticsearch-migration-2021-02-16.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/elasticsearch-migration-2021-02-16.html) diff --git a/docs/reference/make-docker-and-qemu.md b/docs/reference/make-docker-and-qemu.md deleted file mode 100644 index 42bc3decdc8..00000000000 --- a/docs/reference/make-docker-and-qemu.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/make-docker-and-qemu.html) diff --git a/docs/reference/provisioning/scim-token.md b/docs/reference/provisioning/scim-token.md deleted file mode 100644 index 99e6c5f963d..00000000000 --- a/docs/reference/provisioning/scim-token.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/provisioning/scim-token.html) diff --git a/docs/reference/provisioning/scim-via-curl.md b/docs/reference/provisioning/scim-via-curl.md deleted file mode 100644 index ea04af09599..00000000000 --- a/docs/reference/provisioning/scim-via-curl.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/provisioning/scim-via-curl.html) diff --git a/docs/reference/provisioning/wire_scim_token.py b/docs/reference/provisioning/wire_scim_token.py deleted file mode 120000 index 7be5401a613..00000000000 --- a/docs/reference/provisioning/wire_scim_token.py +++ /dev/null @@ -1 +0,0 @@ -../../legacy/reference/provisioning/wire_scim_token.py \ No newline at end of file diff --git a/docs/reference/spar-braindump.md b/docs/reference/spar-braindump.md deleted file mode 100644 index b8e3d27fb99..00000000000 --- a/docs/reference/spar-braindump.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/spar-braindump.html) diff --git a/docs/reference/user/activation.md b/docs/reference/user/activation.md deleted file mode 100644 index 72f1ea2fc97..00000000000 --- a/docs/reference/user/activation.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/user/activation.html) diff --git a/docs/reference/user/connection.md b/docs/reference/user/connection.md deleted file mode 100644 index 8ab24811404..00000000000 --- a/docs/reference/user/connection.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/user/connection.html) diff --git a/docs/reference/user/registration.md b/docs/reference/user/registration.md deleted file mode 100644 index a5147094caf..00000000000 --- a/docs/reference/user/registration.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/user/registration.html) diff --git a/docs/reference/user/rich-info.md b/docs/reference/user/rich-info.md deleted file mode 100644 index 0bd8b7be5b9..00000000000 --- a/docs/reference/user/rich-info.md +++ /dev/null @@ -1 +0,0 @@ -file has moved [here](https://docs.wire.com/developer/reference/user/rich-info.html) diff --git a/docs/src/developer/reference/provisioning/scim-via-curl.md b/docs/src/developer/reference/provisioning/scim-via-curl.md deleted file mode 100644 index aaa2a9eea56..00000000000 --- a/docs/src/developer/reference/provisioning/scim-via-curl.md +++ /dev/null @@ -1 +0,0 @@ -# This page [has gone here](https://docs.wire.com/understand/single-sign-on/main.html#using-scim-via-curl). diff --git a/docs/src/developer/reference/spar-braindump.md b/docs/src/developer/reference/spar-braindump.md index 24011f54ff5..aa3b72c3262 100644 --- a/docs/src/developer/reference/spar-braindump.md +++ b/docs/src/developer/reference/spar-braindump.md @@ -113,8 +113,7 @@ export IDP_ID=... Copy the new metadata file to one of your spar instances. -Ssh into it. If you can't, [the scim -docs](provisioning/scim-via-curl.md) explain how you can create a +Ssh into it. If you can't, [the sso docs](../../understand/single-sign-on/main.rst) explain how you can create a bearer token if you have the admin's login credentials. If you follow that approach, you need to replace all mentions of `-H'Z-User ...'` with `-H'Authorization: Bearer ...'` in the following, and you won't need From 43ac3b3c5380c11d4d65080fc2d890742ac04b96 Mon Sep 17 00:00:00 2001 From: Stefan Matting Date: Wed, 24 Aug 2022 16:40:32 +0200 Subject: [PATCH 25/27] restructure TOC --- docs/src/developer/developer/index.rst | 10 +++ docs/src/developer/index.rst | 96 +------------------------- docs/src/developer/reference/index.rst | 10 +++ 3 files changed, 23 insertions(+), 93 deletions(-) create mode 100644 docs/src/developer/developer/index.rst create mode 100644 docs/src/developer/reference/index.rst diff --git a/docs/src/developer/developer/index.rst b/docs/src/developer/developer/index.rst new file mode 100644 index 00000000000..a8fefaa7706 --- /dev/null +++ b/docs/src/developer/developer/index.rst @@ -0,0 +1,10 @@ +Developer +========= + +.. toctree:: + :titlesonly: + :numbered: + :caption: Contents: + :glob: + + ** diff --git a/docs/src/developer/index.rst b/docs/src/developer/index.rst index 4eabb97d4cd..90df2360f8a 100644 --- a/docs/src/developer/index.rst +++ b/docs/src/developer/index.rst @@ -7,99 +7,9 @@ re-ordering, and they are far from complete, but we hope they will still help you. .. toctree:: - :maxdepth: 1 + :titlesonly: :caption: Contents: :glob: - developer/api-versioning.md <./developer/api-versioning.md> - developer/building.md <./developer/building.md> - developer/cassandra-interaction.md <./developer/cassandra-interaction.md> - developer/changelog.md <./developer/changelog.md> - developer/dependencies.md <./developer/dependencies.md> - developer/editor-setup.md <./developer/editor-setup.md> - developer/features.md <./developer/features.md> - developer/federation-api-conventions.md <./developer/federation-api-conventions.md> - developer/how-to.md <./developer/how-to.md> - developer/linting.md <./developer/linting.md> - developer/processes.md <./developer/processes.md> - developer/scim/storage.md <./developer/scim/storage.md> - developer/servant.md <./developer/servant.md> - developer/testing.md <./developer/testing.md> - reference/config-options.md <./reference/config-options.md> - reference/conversation.md <./reference/conversation.md> - reference/elastic-search.md <./reference/elastic-search.md> - reference/elasticsearch-migration-2021-02-16.md <./reference/elasticsearch-migration-2021-02-16.md> - reference/make-docker-and-qemu.md <./reference/make-docker-and-qemu.md> - reference/provisioning/scim-token.md <./reference/provisioning/scim-token.md> - reference/provisioning/scim-via-curl.md <./reference/provisioning/scim-via-curl.md> - reference/provisioning/wire_scim_token.md <./reference/provisioning/wire_scim_token.md> - reference/spar-braindump.md <./reference/spar-braindump.md> - reference/team/legalhold.md <./reference/team/legalhold.md> - reference/user/activation.md <./reference/user/activation.md> - reference/user/connection.md <./reference/user/connection.md> - reference/user/registration.md <./reference/user/registration.md> - reference/user/rich-info.md <./reference/user/rich-info.md> - -Users ------ - -User lifecycle: - -- `User registration `__ - ``{#RefRegistration}`` -- `User activation `__ - ``{#RefActivation}`` - -User profiles and metadata: - -- `Connections between users `__ - ``{#RefConnection}`` -- `Rich info `__ ``{#RefRichInfo}`` - -SCIM provisioning ------------------ - -We have support for provisioning users via SCIM (`RFC -7664 `__, `RFC -7643 `__). It’s in the beta stage. - -- `Using the SCIM API with - curl `__ - ``{#RefScimViaCurl}`` -- `Authentication via SCIM - tokens `__ ``{#RefScimToken}`` - -Hints ------ - -Internal documentation detailing what you need to know as a Wire backend -developer. All of these documents can and should be referenced in the -code. - -If you’re not a member of the Wire backend team, you might still find -these documents useful, but keep in mind that they are a work in -progress. - -- `Development setup `__ ``{#DevDeps}`` -- `Editor setup `__ ``{#DevEditor}`` -- `Storing SCIM-related data `__ - ``{#DevScimStorage}`` - -Cassandra ---------- - -We use `Cassandra `__ as the primary data -store. It is scalable, has very fast reads and writes, and is -conceptually simple (or at least simpler than SQL databases). - -Some helpful links: - -- `Query - syntax `__ - -- How deletes work in Cassandra: - - - `Understanding - Deletes `__ - - `Cassandra Compaction and Tombstone - Behavior `__ + developer/index.rst + reference/index.rst diff --git a/docs/src/developer/reference/index.rst b/docs/src/developer/reference/index.rst new file mode 100644 index 00000000000..1eb9feedbaa --- /dev/null +++ b/docs/src/developer/reference/index.rst @@ -0,0 +1,10 @@ +Reference +========= + +.. toctree:: + :titlesonly: + :numbered: + :caption: Contents: + :glob: + + ** From c8b408dd18211bacc249b6b9f115470bb2a35afa Mon Sep 17 00:00:00 2001 From: Stefan Matting Date: Wed, 24 Aug 2022 16:44:32 +0200 Subject: [PATCH 26/27] Fix heading levels in multiple sections --- docs/src/developer/developer/building.md | 26 ++--- docs/src/developer/developer/changelog.md | 2 +- docs/src/developer/developer/dependencies.md | 72 ++++++------ docs/src/developer/developer/editor-setup.md | 6 +- .../developer/federation-api-conventions.md | 2 - docs/src/developer/developer/linting.md | 4 +- docs/src/developer/developer/scim/storage.md | 4 +- docs/src/developer/developer/servant.md | 14 +-- .../src/developer/reference/config-options.md | 4 +- docs/src/developer/reference/conversation.md | 4 +- .../reference/make-docker-and-qemu.md | 106 +++++++++--------- .../reference/provisioning/scim-token.md | 4 +- .../src/developer/reference/spar-braindump.md | 6 +- .../developer/reference/user/activation.md | 4 +- .../developer/reference/user/connection.md | 4 +- .../developer/reference/user/registration.md | 2 +- .../src/developer/reference/user/rich-info.md | 4 +- 17 files changed, 142 insertions(+), 126 deletions(-) diff --git a/docs/src/developer/developer/building.md b/docs/src/developer/developer/building.md index edcbe91b78b..2457128bfe4 100644 --- a/docs/src/developer/developer/building.md +++ b/docs/src/developer/developer/building.md @@ -7,33 +7,33 @@ All following commands expect that you've entered the nix-provided build-environ 1. Create a `.envrc.local` file with these contents - ``` +``` export COMPILE_NGINX_USING_NIX=1 export WIRE_BUILD_WITH_CABAL=1 - ``` +``` and reload the direnv via `direnv reload` 2. Create a `cabal.project.local`. This file is not included in wire-server because it disables optimization. - ``` + make cabal.project.local - ``` + This should be re-run whenver a new local cabal package is added to the cabal project. Then the following Makefile targets can be used to compile and test wire-server locally: -``` -# to compile all binaries to ./dist run -make -# to build and install all of galley's executables -make c package=galley + # to compile all binaries to ./dist run + make + + # to build and install all of galley's executables + make c package=galley + + # also run galley's unit tests + make c package=galley test=1 -# also run galley's unit tests -make c package=galley test=1 -``` ## Troubleshooting @@ -49,7 +49,7 @@ The easiest course of action is to to remove these directories via: make full-clean ``` -# How to run integration tests +## How to run integration tests Integration tests require all of the haskell services (brig, galley, cannon, gundeck, proxy, cargohold, spar) to be correctly configured and running, before being able to execute e.g. the `brig-integration` binary. The test for brig also starts nginz, so make sure it has been built before. These services require most of the deployment dependencies as seen in the architecture diagram to also be available: diff --git a/docs/src/developer/developer/changelog.md b/docs/src/developer/developer/changelog.md index f6477ec1620..6d1640ed85b 100644 --- a/docs/src/developer/developer/changelog.md +++ b/docs/src/developer/developer/changelog.md @@ -1,4 +1,4 @@ -# changelog +# Changelog The wire-server repo has a process for changelog editing that prevents merge conflicts and enforces a consistent structure to the release diff --git a/docs/src/developer/developer/dependencies.md b/docs/src/developer/developer/dependencies.md index b9bec91c534..15896f6d75d 100644 --- a/docs/src/developer/developer/dependencies.md +++ b/docs/src/developer/developer/dependencies.md @@ -1,4 +1,6 @@ -# Dependencies {#DevDeps} +# Dependencies + +Reference: {#DevDeps} This page documents how to install necessary dependencies to work with the wire-server code base. @@ -78,11 +80,11 @@ If `openssl-dev` does not work for you, try `libssl-dev`. ### Arch: -``` -# You might also need 'sudo pacman -S base-devel' if you haven't -# installed the base-devel group already. -sudo pacman -S geoip snappy icu openssl ncurses-compat-libs -``` + ``` + # You might also need 'sudo pacman -S base-devel' if you haven't + # installed the base-devel group already. + sudo pacman -S geoip snappy icu openssl ncurses-compat-libs + ``` ### macOS: @@ -129,11 +131,11 @@ sudo apt install haskell-stack -y ### Generic -```bash -curl -sSL https://get.haskellstack.org/ | sh -# or -wget -qO- https://get.haskellstack.org/ | sh -``` + ```bash + curl -sSL https://get.haskellstack.org/ | sh + # or + wget -qO- https://get.haskellstack.org/ | sh + ``` ## Rust @@ -168,18 +170,18 @@ dpkg -i target/release/cryptobox*.deb ``` ### Generic -```bash -export TARGET_LIB="$HOME/.wire-dev/lib" -export TARGET_INCLUDE="$HOME/.wire-dev/include" -mkdir -p "$TARGET_LIB" -mkdir -p "$TARGET_INCLUDE" -git clone https://github.com/wireapp/cryptobox-c && cd cryptobox-c -make install - -# Add cryptobox-c to ldconfig -sudo bash -c "echo \"${TARGET_LIB}\" > /etc/ld.so.conf.d/cryptobox.conf" -sudo ldconfig -``` + ```bash + export TARGET_LIB="$HOME/.wire-dev/lib" + export TARGET_INCLUDE="$HOME/.wire-dev/include" + mkdir -p "$TARGET_LIB" + mkdir -p "$TARGET_INCLUDE" + git clone https://github.com/wireapp/cryptobox-c && cd cryptobox-c + make install + + # Add cryptobox-c to ldconfig + sudo bash -c "echo \"${TARGET_LIB}\" > /etc/ld.so.conf.d/cryptobox.conf" + sudo ldconfig + ``` Make sure stack knows where to find it. In `~/.stack/config.yaml` add: @@ -228,22 +230,22 @@ Requirements: ### Telepresence example usage: -``` -# terminal 1 -telepresence --namespace "$NAMESPACE" --also-proxy cassandra-ephemeral -``` + ``` + # terminal 1 + telepresence --namespace "$NAMESPACE" --also-proxy cassandra-ephemeral + ``` -``` -# terminal 2 -curl http://elasticsearch-ephemeral:9200 -``` + ``` + # terminal 2 + curl http://elasticsearch-ephemeral:9200 + ``` ### Telepresence example usage 2: -``` -# just one terminal -telepresence --namespace "$NAMESPACE" --also-proxy cassandra-ephemeral --run bash -c "curl http://elasticsearch-ephemeral:9200" -``` + ``` + # just one terminal + telepresence --namespace "$NAMESPACE" --also-proxy cassandra-ephemeral --run bash -c "curl http://elasticsearch-ephemeral:9200" + ``` ### Telepresence usage discussion: diff --git a/docs/src/developer/developer/editor-setup.md b/docs/src/developer/developer/editor-setup.md index 6e621defcc3..7b39f8a463f 100644 --- a/docs/src/developer/developer/editor-setup.md +++ b/docs/src/developer/developer/editor-setup.md @@ -1,4 +1,6 @@ -# Editor setup {#DevEditor} +# Editor setup + +Reference: {#DevEditor} This page provides tips for setting up editors to work with the Wire codebase. @@ -114,4 +116,4 @@ Setup steps: An alternative way to make these dependencies accessible to VSCode is to start it in the `direnv` environment. I.e. from a shell that's current working directory is in the project. The drawbacks of this approach are -that it only works locally (not on a remote connection) and one VSCode process needs to be started per project. \ No newline at end of file +that it only works locally (not on a remote connection) and one VSCode process needs to be started per project. diff --git a/docs/src/developer/developer/federation-api-conventions.md b/docs/src/developer/developer/federation-api-conventions.md index 84b73a8a6c0..612a4eb67ed 100644 --- a/docs/src/developer/developer/federation-api-conventions.md +++ b/docs/src/developer/developer/federation-api-conventions.md @@ -1,5 +1,3 @@ - - # Federation API Conventions - All endpoints must start with `/federation/` diff --git a/docs/src/developer/developer/linting.md b/docs/src/developer/developer/linting.md index 5dcbf75ab0f..3a1bcbecb6a 100644 --- a/docs/src/developer/developer/linting.md +++ b/docs/src/developer/developer/linting.md @@ -1,6 +1,6 @@ # Linting -# HLint +## HLint To run [HLint](https://github.com/ndmitchell/hlint) you need it's binary, e.g. by executing: @@ -21,7 +21,7 @@ To run it on a sub-project: hlint services/federator ``` -# Stan +## Stan To run [Stan](https://github.com/kowainik/stan), you need it's binary compiled by the same GHC version as used in the project. diff --git a/docs/src/developer/developer/scim/storage.md b/docs/src/developer/developer/scim/storage.md index bcf64c64154..6fdfcd5ffe8 100644 --- a/docs/src/developer/developer/scim/storage.md +++ b/docs/src/developer/developer/scim/storage.md @@ -1,4 +1,6 @@ -# Storing SCIM-related data {#DevScimStorage} +# Storing SCIM-related data + +Reference: {#DevScimStorage} _Author: Artyom Kazak, Matthias Fischmann_ diff --git a/docs/src/developer/developer/servant.md b/docs/src/developer/developer/servant.md index 426b7b89fb7..4bc2ea858e8 100644 --- a/docs/src/developer/developer/servant.md +++ b/docs/src/developer/developer/servant.md @@ -1,4 +1,4 @@ -# Introduction +# Servant We currently use Servant for the public (i.e. client-facing) API in brig, galley and spar, as well as for their federation (i.e. server-to-server) and internal API. @@ -6,11 +6,11 @@ Client-facing APIs are defined in `Wire.API.Routes.Public.{Brig,Galley}`. Intern Our APIs are able to generate Swagger documentation semi-automatically using `servant-swagger2`. The `schema-profunctor` library (see [`README.md`](https://github.com/wireapp/wire-server/blob/develop/libs/schema-profunctor/README.md) in `libs/schema-profunctor`) is used to create "schemas" for the input and output types used in the Servant APIs. A schema contains all the information needed to serialise/deserialise JSON values, as well as the documentation and metadata needed to generate Swagger. -# Combinators +## Combinators We have employed a few custom combinators to try to keep HTTP concerns and vocabulary out of the API handlers that actually implement the functionality of the API. -## `ZAuth` +### `ZAuth` This is a family of combinators to handle the headers that nginx adds to requests. We currently have: @@ -19,21 +19,21 @@ This is a family of combinators to handle the headers that nginx adds to request - `ZConn`: extracts the `ConnId` in the `Z-Connection` header. - `ZConversation`: extracts the `ConvId` in the `Z-Conversation` header. -## `MultiVerb` +### `MultiVerb` This is an alternative to `UVerb`, designed to prevent any HTTP-specific information from leaking into the type of the handler. Use this for endpoints that can return multiple responses. -## `CanThrow` +### `CanThrow` This can be used to add an error response to the Swagger documentation. In services that use polysemy for error handling (currently only Galley), it also adds a corresponding error effect to the type of the handler. The argument of `CanThrow` can be of a custom kind, usually a service-specific error kind (such as `GalleyError`, `BrigError`, etc...), but kind `*` can also be used. Note that error types can also be turned into `MultiVerb` responses using the `ErrorResponse` combinator. This is useful for handlers that can return errors as part of their return type, instead of simply throwing them as IO exceptions or using polysemy. If an error is part of `MultiVerb`, there is no need to also report it with `CanThrow`. -## `QualifiedCapture` +### `QualifiedCapture` This is a capture combinator for a path that looks like `/:domain/:value`, where `value` is of some arbitrary type `a`. The value is returned as a value of type `Qualified a`, which can then be used in federation-aware endpoints. -# Error handling +## Error handling Several layers of error handling are involved when serving a request. A handler in service code (e.g. Brig or Galley) can: diff --git a/docs/src/developer/reference/config-options.md b/docs/src/developer/reference/config-options.md index 7a5a400e658..8a74338aa70 100644 --- a/docs/src/developer/reference/config-options.md +++ b/docs/src/developer/reference/config-options.md @@ -1,4 +1,6 @@ -# Config Options {#RefConfigOptions} +# Config Options + +Reference: {#RefConfigOptions} Fragment. diff --git a/docs/src/developer/reference/conversation.md b/docs/src/developer/reference/conversation.md index 1d4af8569e6..eedbfa7ce0b 100644 --- a/docs/src/developer/reference/conversation.md +++ b/docs/src/developer/reference/conversation.md @@ -1,4 +1,6 @@ -# Creating and populating conversations {#RefCreateAndPopulateConvs} +# Creating and populating conversations + +Reference: {#RefCreateAndPopulateConvs} _Author: Matthias Fischmann_ diff --git a/docs/src/developer/reference/make-docker-and-qemu.md b/docs/src/developer/reference/make-docker-and-qemu.md index 3088eda1a0d..a7c10f06cfc 100644 --- a/docs/src/developer/reference/make-docker-and-qemu.md +++ b/docs/src/developer/reference/make-docker-and-qemu.md @@ -1,9 +1,9 @@ -# About this document: +# Make docker and QEMU This document is written with the goal of explaining https://github.com/wireapp/wire-server/pull/622 well enough that someone can honestly review it. :) In this document, we're going to rapidly bounce back and forth between GNU make, bash, GNU sed, Docker, and QEMU. -# What does this Makefile do? Why was it created? +## What does this Makefile do? Why was it created? To answer that, we're going to have to go back to Wire-Server, specifically, our integration tests. Integration tests are run locally on all of our machines, in order to ensure that changes we make to the Wire backend do not break currently existing functionality. In order to simulate the components that wire's backend depends on (s3, cassandra, redis, etc..), we use a series of docker images. These docker images are downloaded from dockerhub, are maintained (or not maintained) by outside parties, and are built by those parties. @@ -13,13 +13,13 @@ This Makefile contains rules that allow our Mac users to build all of the docker It builds non-AMD64 images on linux by using QEMU, a system emulator, to allow docker to run images that are not built for the architecture the system is currently running on. This is full system emulation, like many video game engines you're probably familiar with. You know how you have to throw gobs of hardware at a machine, to play a game written for a gaming system 20 years ago? This is similarly slow. To work around this, the Makefile is written in a manner that allows us to build many docker images at once, to take advantage of the fact that most of us have many processor cores lying around doing not-all-much. -# What does this get us? +## What does this get us? To start with, the resulting docker images allow us to tune the JVM settings on cassandra and elasticsearch, resulting in lower memory consumption, and faster integration tests that don't impact our systems as much. Additionally, it allows us more control of the docker images we're depending on, so that another leftpad incident on docker doesn't impact us. As things stand, any of the developers of these docker images can upload a new docker image that does Very Bad Things(tm), and we'll gladly download and run it many times a day. Building these images ourselves from known good GIT revisions prevents this. Additionally, the multi-architecture approach allows us to be one step closer to running the backend on more esoteric systems, like a Raspberry pi, or an AWS A instance, both of which are built on the ARM architecture. Or, if rumour is to be believed, the next release of MacBook Pros. :) -# Breaking it down: +## Breaking it down: -## Docker: +### Docker: to start with, we're going to have to get a bit into some docker architecture. We all have used docker, and pretty much understand the following workflow: @@ -27,19 +27,19 @@ I build a docker image from a Dockerfile and maybe some additions, I upload it t While this workflow works well for working with a single architecture, we're going to have to introduce some new concepts in order to support the multiple architecture way of building docker files. -### Manifest files. +#### Manifest files. Manifest files are agenerated by docker and contain references to multiple docker images, one for each architecture a given docker image has been built for. Each image in the manifest file is tagged with the architecture that the image is built for. Docker contains just enough built-in logic to interpret a manifest file on dockerhub, and download an image that matches the architecture that docker was built for. When using a manifest file, this is how docker determines what image to download. -### A Manifest centric Workflow: +#### A Manifest centric Workflow: If you're building a docker image for multiple architectures, you want a Manifest, so that docker automatically grabs the right image for the user's machine. This changes our workflow from earlier quite a bit: I build a docker image from a Dockerfile, and I build other images from slightly different versions of this Dockerfile (more on this later). I tag these images with a suffix, so that I can tell them apart. I upload the images to dockerhub, retaining the tags that differentiate the diffenent versions from each other. I create a manifest file, referring to the images that have been pushed to DockerHub, and upload the manifest file to DockerHub. People can download and use the image from dockerhub by refering to the tag of the manifest file. I can share the Dockerfile and additions via git, on dockerhub, and others can build their own images from it. -#### What does this look like? +##### What does this look like? All of us on the team are using AMD64 based machines, so in this example, we're going to build one image for AMD64, and one for it's predecessor architecture, I386. We're going to build the SMTP server image we depend on, from https://hub.docker.com/r/namshi/smtp. We're going to use a known safe git revision, and use some minor GNU sed to generate architecture dependent Dockerfiles from the Dockerfile in git. Everyone should be able to do this on your laptops. @@ -76,13 +76,13 @@ $ That wasn't so bad, was it? -##### what was that SED all about? +###### what was that SED all about? The sed commands used above accomplished two things. One, they changed out the MAINTAINER line in the Dockerfile, to indicate that I am the maintainer of this docker image. Two, for the 386 image, it specified that Docker was to start by using the i386 version of debian to base the image off of, not the AMD64 version. we did not need to make that change to the AMD64 version of the Dockerfile, because Docker on our local machine automatically downloads AMD64 images, since our copies of docker were built on AMD64 machines. -##### OK, what was the --amend on the docker manifest create line? +###### OK, what was the --amend on the docker manifest create line? Docker creates manifest files, and stores them in your local docker. I haven't found a good way to remove them, so instead, I add --amend, so that if one already exists, docker overwrites the locally stored file, instead of just telling you one already exists, and exiting with an error. -##### What does a manifest file look like? +###### What does a manifest file look like? to look at a manifest file (local or remote), use 'docker manifest inspect'. for example, here's the original namshi/smtp manifest. ```bash @@ -160,32 +160,32 @@ This is very different. instead of showing layers, it has the SHASUMs of the ima That's it as far as the docker parts of this. Simple, right? :) -### Limits of Manifest files: +#### Limits of Manifest files: I can't figure out how to delete local manifest files. I haven't figured out how to point to local images in a manifest file. this means if we use the name of a manifest in our Docker compose configuration, docker will go out to dockerhub for the image, rather than using a new image we just built, and we have to build a manifest file AFTER the push do dockerhub has been completed. -## QEMU + BinFmt Support: +### QEMU + BinFmt Support: The previous section has shown us how docker handles multiple architectures, this section is going to cover abusing the BinFmt linux kernel extensions and the QEMU system emulator to allow us to build docker images for non-native architectures, like arm, arm64, ppl64le, etc. -### About QEMU: +#### About QEMU: QEMU is a full system emulator, and a userspace emulator. QEMU's system emulation means that you can start qemu with disk images, ISOs, etc, for a supported architecture, and it will emulate a whole system around it, showing it's display in a window on your system. We're not going to be using this, and instead use it's userspace emulation. QEMU's userspace emulation allows you to download a program written for a different processor, and assuming you have the appropriate libraries, DLLs, etc... you can just run it locally. Typically this involves either having a program with no dependencies, or installing a set of system libraries on your machine for the target architecture alongside your current set of libraries. -### About BinFmt Support: +#### About BinFmt Support: BinFmt support is a set of extensions to the linux kernel that allow you to specify an interpreter for binaries of a certain pattern (magic number, ELF header, .EXE header, etc), so that when you attempt to execute them, the kernel will launch the interpreter of your choice, passing it the path to the binary you tried to execute. On my debian machine, it is used for python by default. Many people use this support for executing windows executables on linux using the WINE package, which contains a re-implementation of the Windows system libraries. The Linux kernel's BinFmt module can be set to look for an interpreter at run time, or to load the interpreter into memory when it is configured. The packages we're going to set up and exercise in this stage use the "load when you configure" approach. This is useful, so than when you're operating in a docker container, you don't have to place the system emulator in the docker container itsself for the kernel to find it. -### Installing QEMU with BinFmt support: +#### Installing QEMU with BinFmt support: Debian's qemu-user-static package sets this all up for you. as root: ```bash -# apt install qemu-user-static +## apt install qemu-user-static Reading package lists... Done Building dependency tree Reading state information... Done @@ -200,11 +200,11 @@ The following NEW packages will be installed: Unpacking qemu-user-static (1:3.1+dfsg-4) ... Setting up qemu-user-static (1:3.1+dfsg-4) ... Processing triggers for man-db (2.8.5-2) ... -# +## ``` -### Verifying it's configuration: +#### Verifying it's configuration: The linux kernel's BinFmt support is configured through a series of 'fake' files, in the /proc/sys/fs/binfmt_misc directory. by default, this directory contains the following: @@ -274,7 +274,7 @@ $ the 'F' in the flags field of that file indicates we're loading the emulators into ram. note that this file specifies the interpreter by it's full path, and a magic and mask field. these are the values the kernel looks for when executing a file, and if it finds them, launches the interpreter. -### Putting BinFmt and QEMU to work +#### Putting BinFmt and QEMU to work To test all of this, let's try executing something that's not built for our machine. We're going to try to launch a copy of SASH, the Staticly linked Almquist Shell. Because this is statically linked, we are not going to need to install any system libraries to launch it. We're going to launch an ARM copy, which normally wouldn't think of running on our machines. First, we'll grab a copy with wget. @@ -328,7 +328,7 @@ demo > ``` -## QEMU, BinFmt, and Docker (Oh my!) +### QEMU, BinFmt, and Docker (Oh my!) After following the directions in the last two sections, you've created two docker images (one for i386, one for AMD64), created a manifest referring to them, set up for linux to load qemu and use it, and launched a binary for another architecture. @@ -336,7 +336,7 @@ Creating non-native docker images can now be done very similar to how i386 was d Because you are using a system emulator, your docker builds for non-x86 will be slower. additionally, the emulators are not perfect, so some images won't build. finally, code is just less tested on machines that are not an AMD64 machine, so there are generally more bugs. -### Arm Complications: +#### Arm Complications: The 32 bit version of arm is actually divided into versions, and not all linux distributions are available for all versions. arm32v5 and arm32v7 are supported by debian, while arm32v6 is supported by alpine. This variant must be specified during manifest construction, so to continue with our current example, these are the commands for tagging the docker images for our arm32v5 and arm32v7 builds of smtp: ```bash $ docker manifest annotate julialongtin/smtp:0.0.9 julialongtin/smtp:0.0.9-arm32v5 --arch arm --variant 5 @@ -344,14 +344,14 @@ $ docker manifest annotate julialongtin/smtp:0.0.9 julialongtin/smtp:0.0.9-arm32 ``` -# Into the GNU Make Abyss +## Into the GNU Make Abyss Now that we've done all of the above, we should be capable of working with docker images independent of the architecture we're targeting. Now, into the rabit hole we go, automating everything with GNU Make -## Why Make? +### Why Make? GNU make is designed to build targets by looking at the environment it's in, and executing a number of rules depending on what it sees, and what it has been requested to do. The Makefile we're going to look through does all of the above, along with making some minor changes to the docker images. It does this in parallel, calling as many of the commands at once as possible, in order to take advantage of idle cores. -## Using the Makefile +### Using the Makefile Before we take the Makefile apart, let's go over using it. @@ -401,8 +401,8 @@ If we want to use these images in our docker compose, we can edit the docker com ports: - "127.0.0.1:9042:9042" environment: -# what's present in the jvm.options file by default. -# - "CS_JAVA_OPTIONS=-Xmx1024M -Xms1024M -Xmn200M" +## what's present in the jvm.options file by default. +## - "CS_JAVA_OPTIONS=-Xmx1024M -Xms1024M -Xmn200M" - "CS_JVM_OPTIONS=-Xmx128M -Xms128M -Xmn50M" networks: - demo_wire @@ -410,15 +410,15 @@ If we want to use these images in our docker compose, we can edit the docker com To remove all of the git repositories containing the Dockerfiles we download to build these images, we can run `make clean`. There is also the option to run `make cleandocker` to REMOVE ALL OF THE DOCKER IMAGES ON YOUR MACHINE. careful with that one. Note that docker makes good use of caching, so running 'make clean' and the same make command you used to build the images will complete really fast, as docker does not actually need to rebuild the images. -## Reading through the Makefile +### Reading through the Makefile OK, now that we have a handle on what it does, and how to use it, let's get into the Makefile itsself. A Makefile is a series of rules for performing tasks, variables used when creating those tasks, and some minimal functions and conditional structures. Rules are implemented as groups of bash commands, where each line is handled by a new bash interpreter. Personally, I think it 'feels functiony', only without a type system and with lots of side effects. Like if bash tried to be functional. -### Variables +#### Variables -#### Overrideable Variables +##### Overrideable Variables the make language has multiple types of variables and variable assignments. To begin with, let's look at the variables we used in the last step. ```bash $ cat Makefile | grep "?=" @@ -451,7 +451,7 @@ LOCALARCH and the assignments for ARCHES and NAMES are a bit different. LOCALARC Note the block of COMMIT IDs. This is in case we want to experiment with newer releases of each of the docker images we're using. Fixing what we're using to a commit ID makes it much harder for an upstream source to send us malicious code. -#### Non-Overrideable Variables +##### Non-Overrideable Variables The following group of variables use a different assignment operator, that tells make not to look in the environment first. ```bash $ cat Makefile | grep ":=" @@ -489,7 +489,7 @@ LOCALDEBARCH is a variable set by executing a small snippet of bash. The snippet NOMANIFEST lists images that need a work-around for fetching image dependencies for specific architectures. You know how we added the name of the architecture BEFORE the image name in the dockerfiles? well, in the case of the dependencies of the images listed here, dockerhub isn't supporting that. DockerHub is supporting that form only for 'official' docker images, like alpine, debian, etc. as a result, in order to fetch an architecture specific version of the dependencies of these images, we need to add a - suffix. like -386 -arm32v7, etc. -### Conditionals +#### Conditionals We don't make much use of conditionals, but there are three total uses in this Makefile. let's take a look at them. In order to look at our conditionals (and many other sections of this Makefile later), we're going to abuse sed. If you're not comfortable with the sed shown here, or are having problems getting it to work, you can instead just open the Makefile in your favorite text editor, and search around. I abuse sed here for both brevity, and to encourage the reader to understand complicated sed commands, for when we are using them later IN the Makefile. @@ -524,28 +524,28 @@ Now, back to our sed abuse. SED is a stream editor, and quite a powerful one. In this case, we're using it for a multi-line search. we're supplying the -n option, which squashes all output, except what sed is told specificly to print something with a command. Let's look at each of the commands in that statement seperately. ```sed -# find a line that has 'ifeq' in it. +## find a line that has 'ifeq' in it. /ifeq/ -# begin a block of commands. every command in the block should be seperated by a semicolon. +## begin a block of commands. every command in the block should be seperated by a semicolon. { -# create an anchor, that is to say, a point that can be branched to. +## create an anchor, that is to say, a point that can be branched to. :n; -# Append the next line into the parameter space. so now, for the first block, the hold parameter space would include "ifeq ($(LOCALARCH),)\n $(error LOCALARCH is empty, you may need to supply it.)". +## Append the next line into the parameter space. so now, for the first block, the hold parameter space would include "ifeq ($(LOCALARCH),)\n $(error LOCALARCH is empty, you may need to supply it.)". N; -# Replace the two spaces in the parameter space with one space. +## Replace the two spaces in the parameter space with one space. s/\n /\n /; -# If the previous 's' command found something, and changed something, go to our label. +## If the previous 's' command found something, and changed something, go to our label. tn; -# print the contents of the parameter space. +## print the contents of the parameter space. p -# close the block of commands. +## close the block of commands. } ``` ... Simple, right? note that the contents above can be stored to a file, and run with sed's "-f" command, for more complicated sed scripts. Sed is turing complete, so... things like tetris have been written in it. My longest sed scripts do things like sanity check OS install procedures, or change binaryish protocols into xmlish forms. -### Functions +#### Functions Make has a concept of functions, and the first two functions we use are a bit haskell inspired. SED ABUSE: @@ -607,7 +607,7 @@ $ cat Makefile | sed -n '/^[a-z]*=/p' ``` Again, we're going to use sed in '-n' mode, supressing all output except the output we are searching for. /PATTERN/ searches the lines of the input for a pattern, and if it's found, the command afterward is executed, which is a 'p' for print, in this case. the patern given is '^[a-z]*='. The '^' at the beginning means 'look for this patern at the beginning of the line, and the '=' at the end is the equal sign we were looking for. '[a-z]*' is us using a character class. character classes are sedspeak for sets of characters. they can be individually listed, or in this case, be a character range. the '*' after the character class just means "look for these characters any number of times". technically, that means a line starting in '=' would work (since zero is any number of times), but luckily, our file doesn't contain lines starting with =, as this is not valid make syntax. -### Rules. +#### Rules. Traditionally, makefiles are pretty simple. they are used to build a piece of software on your local machine, so you don't have to memorize all of the steps, and can type 'make', and have it just done. A simple Makefile looks like the following: ```make @@ -641,7 +641,7 @@ target: prerequisites The commands to build a thing (recipe lines) are prefaced with a tab character, and not spaces. Each line is executed in a seperate shell instance. -#### The roots of the trees +##### The roots of the trees In the section where we showed you how to use our Makefile, we were calling 'make' with an option, such as push-all, build-smtp, names, or clean. We're now going to show you the rules that implement these options. @@ -711,7 +711,7 @@ $ cat Makefile | sed -n -E '/^(.SECOND)/{:n;N;s/\n\t/\n /;tn;p}' | less build-% also uses the same 'fake recipe' trick as push-%, that is, having a recipe that does nothing, to trick make into letting you run this. -#### One Level Deeper +##### One Level Deeper The rules you've seen so far were intended for user interaction. they are all rules that the end user of this Makefile picks between, when deciding what they want this makefile to do. Let's look at the rules that these depend on. @@ -737,7 +737,7 @@ manifest-create-%: $$(foreach arch,$$(call goodarches,%), upload-$$(arch)-$$*) manifest-push depends on manifest-annotate, which depends on manifest-create, that depends on upload-... so when make tries to push a manifest, it makes sure an image has been uploaded, then creates a manifest, then annotates the manifest. We're basically writing rules for each step of our manifest, only backwards. continuing this pattern, the last thing we will depend on will be the rules that actually download the dockerfiles from git. -#### Dependency Resolving +##### Dependency Resolving We've covered the entry points of this Makefile, and the chained dependencies that create, annotate, and upload a manifest file. now, we get into two seriously complicated sets of rules, the upload rules and the create rules. These accomplish their tasks of uploading and building docker containers, but at the same time, they accomplish our dependency resolution. Let's take a look. @@ -788,7 +788,7 @@ create-%, depend-create-%, and depend-subcreate-% work similarly to the upload r It's worth noting that for all of these *create* and *upload* rules, we pipe the output of docker to cat, which causes docker to stop trying to draw progress bars. This seriously cleans up the -#### Building Dockerfiles. +##### Building Dockerfiles. There are two rules for creating Dockerfiles, and we decide in the *create* rules which of these to use by looking at the NOMANIFEST variable, and adding -NOMANIFEST in the name of the rule we depend on for dockerfile creation. @@ -825,13 +825,13 @@ The substitution section of this sed command uses the \1 and \2 variable referen Because we are using that sed command in a Makefile, we have to double up the "$" symbol, to prevent make from interpreting it as a variable. In the first sed command in these rules, we're also doing some minor escaping, adding a '\' in front of some quotes, so that our substitution of the maintainer has quotes around the email address. -#### Downloading Dockerfiles +##### Downloading Dockerfiles Finally, we are at the bottom of our dependency tree. We've followed this is reverse order, but when we actually ask for things to be pushed, or to be built, these rules are the first ones run. There are a lot of these, of various complexities, so let's start with the simple ones first. -##### Simple Checkout +###### Simple Checkout ```bash $ cat Makefile | sed -n -E '/^(smtp|dynamo|minio)/{:n;N;s/\n\t/\n /;tn;p}' @@ -851,7 +851,7 @@ minio/Dockerfile: These rules are simple. They git clone a repo, then reset the repo to a known good revision. This isolates us from potential breakage from upstreams, and prevents someone from stealing git credentials for our upstreams, and using those credentials to make a malignant version. -##### Checkout with Modifications +###### Checkout with Modifications A bit more complex rule is localstack/Dockerfile: ```bash @@ -889,7 +889,7 @@ SED ABUSE: To disable the installation of docker here, we do something a bit hacky. we find the line with 'install Docker' on it, we pull the next 5 lines into the pattern buffer, then delete them. This is effectively just a multiline delete. we use the -i.bak command line, just like the last sed abuse. neat and simple. -##### Checkout, Copy, Modify +###### Checkout, Copy, Modify Some of the git repositories that we depend on do not store the Dockerfile in the root of the repository. instead, they have one large repository, with many directories containing many docker images. In these cases, we use git to check out the repository into a directory with the name of the image followed by '-all', then copy the directory we want out of the tree. @@ -980,7 +980,7 @@ Structurally, the first, second, and third sed command are all pretty standard t Note that when we wrote our 'clean' rule, we added these '-all' directories manually, to make sure they would get deleted. -##### Checkout, Copy, Modify Multiline +###### Checkout, Copy, Modify Multiline elasticsearch and cassandra's checkouts are complicated, as they do a bit of injection of code into the docker entrypoint script. The entrypoint script is the script that is launched when you run a docker image. It's responsible for reading in environment variables, setting up the service that the docker image is supposed to run, and then running the service. For both elasticsearch and cassandra, we do a multiline insert, and we do it with multiple chained commands. @@ -1063,10 +1063,10 @@ This substitution command uses slashes as its separators. it starts by anchoring The cassandra/Dockerfile rule is almost identical to this last rule, only substituting out the name of the variable we expect from docker to CS_JVM_OPTIONS, and changing the path to the jvm.options file. -# Pitfalls I fell into writing this. +## Pitfalls I fell into writing this. The first large mistake I made when writing this, is that the root of the makefile's dependency tree contained both images that had dependencies, and the dependent images themselves. This had me writing methods to keep the image build process from stepping on itsself. what was happening is that, in the case of the airdock-* and localstack images, when trying to build all of the images at once, make would race all the way down to the git clone steps, and run the git clone multiple times at the same time, where it just needs to be run once. The second was that I didn't really understand that manifest files refer to dockerhub only, not to the local machine. This was giving me similar race conditions, where an image build for architecture A would complete, and try to build the manifest when architecture B was still building. -The third was writing really complicated SED and BASH and MAKE. ;p \ No newline at end of file +The third was writing really complicated SED and BASH and MAKE. ;p diff --git a/docs/src/developer/reference/provisioning/scim-token.md b/docs/src/developer/reference/provisioning/scim-token.md index b7ae891de53..165e635d0c2 100644 --- a/docs/src/developer/reference/provisioning/scim-token.md +++ b/docs/src/developer/reference/provisioning/scim-token.md @@ -1,4 +1,6 @@ -# SCIM tokens {#RefScimToken} +# SCIM tokens + +Reference: {#RefScimToken} _Author: Artyom Kazak_ diff --git a/docs/src/developer/reference/spar-braindump.md b/docs/src/developer/reference/spar-braindump.md index aa3b72c3262..94d9b557970 100644 --- a/docs/src/developer/reference/spar-braindump.md +++ b/docs/src/developer/reference/spar-braindump.md @@ -1,11 +1,11 @@ -# Spar braindump {#SparBrainDump} +# Spar braindump + +Reference: {#SparBrainDump} _Author: Matthias Fischmann_ --- -# the spar service for user provisioning (scim) and authentication (saml) - a brain dump - this is a mix of information on inmplementation details, architecture, and operation. it should probably be sorted into different places in the future, but if you can't find any more well-structured diff --git a/docs/src/developer/reference/user/activation.md b/docs/src/developer/reference/user/activation.md index dbea703730f..723457ca7e9 100644 --- a/docs/src/developer/reference/user/activation.md +++ b/docs/src/developer/reference/user/activation.md @@ -1,4 +1,6 @@ -# Activation {#RefActivation} +# User Activation + +Reference: {#RefActivation} _Author: Artyom Kazak_ diff --git a/docs/src/developer/reference/user/connection.md b/docs/src/developer/reference/user/connection.md index 1f6d9f1f400..aee2506e22e 100644 --- a/docs/src/developer/reference/user/connection.md +++ b/docs/src/developer/reference/user/connection.md @@ -1,4 +1,6 @@ -# Connection {#RefConnection} +# Connection + +Reference: {#RefConnection} Two users can be _connected_ or not. If the users are connected, each of them can: diff --git a/docs/src/developer/reference/user/registration.md b/docs/src/developer/reference/user/registration.md index 6662885bc77..90fb353d583 100644 --- a/docs/src/developer/reference/user/registration.md +++ b/docs/src/developer/reference/user/registration.md @@ -1,4 +1,4 @@ -# Registration +# User Registration (RefRegistration)= _Authors: Artyom Kazak, Matthias Fischmann_ diff --git a/docs/src/developer/reference/user/rich-info.md b/docs/src/developer/reference/user/rich-info.md index ec40a2fd599..6f8c6b666cd 100644 --- a/docs/src/developer/reference/user/rich-info.md +++ b/docs/src/developer/reference/user/rich-info.md @@ -1,4 +1,6 @@ -# Rich info {#RefRichInfo} +# User Rich info + +Reference: {#RefRichInfo} _Author: Artyom Kazak_ From bd25a660fc01895ee7e37807e456ab4e99492e2a Mon Sep 17 00:00:00 2001 From: Stefan Matting Date: Wed, 24 Aug 2022 17:08:26 +0200 Subject: [PATCH 27/27] Delete wire_scim_token.md --- .../reference/provisioning/wire_scim_token.md | 111 ------------------ 1 file changed, 111 deletions(-) delete mode 100644 docs/src/developer/reference/provisioning/wire_scim_token.md diff --git a/docs/src/developer/reference/provisioning/wire_scim_token.md b/docs/src/developer/reference/provisioning/wire_scim_token.md deleted file mode 100644 index 28701d5be20..00000000000 --- a/docs/src/developer/reference/provisioning/wire_scim_token.md +++ /dev/null @@ -1,111 +0,0 @@ -# Some python code - -``` -#!/usr/bin/env python3 -# -# This file is part of the Wire Server implementation. -# -# Copyright (C) 2020 Wire Swiss GmbH -# -# This program is free software: you can redistribute it and/or modify it under -# the terms of the GNU Affero General Public License as published by the Free -# Software Foundation, either version 3 of the License, or (at your option) any -# later version. -# -# This program is distributed in the hope that it will be useful, but WITHOUT -# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS -# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more -# details. -# -# You should have received a copy of the GNU Affero General Public License along -# with this program. If not, see . - -from __future__ import print_function - -# NOTE: This python script requires the "requests" library to be installed. - -# Change this if you are running your own instance of Wire. -BACKEND_URL='https://prod-nginz-https.wire.com' - -import sys -import getpass -from requests import Request, Session -import requests -import json -import datetime - -session = None - -def init_session(): - global session - session = Session() - session.headers.update({'User-Agent': "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36"}) - -def post(url): - return Request('POST', url) - -def get(url): - return Request('GET', url) - -def set_bearer_token(request, token): - request.headers['Authorization'] = 'Bearer ' + token - -def backend(path): - return BACKEND_URL + path - -def has_json_content(response): - content_type = response.headers.get('Content-Type') - if content_type is not None: - return (content_type.startswith('application/json') - or content_type == 'application/scim+json;charset=utf-8') - else: - return False - -def send_request(session, request): - response = session.send(session.prepare_request(request)) - if 200 <= response.status_code and response.status_code < 300: - if has_json_content(response): - return response.json() - else: - return response - else: - print(f"Request failed {request.url}", file=sys.stderr) - if has_json_content(response): - tpl = response, response.json() - else: - tpl = response, response.content - print(tpl, file=sys.stderr) - exit(1) - -def create_bearer(email, password): - r = post(backend('/login?persist=false')) - r.headers['Accept'] = 'application/json' - r.json = {'email': email, 'password': password} - return send_request(session, r) - -def create_scim_token(admin_password, token): - r = post(backend('/scim/auth-tokens')) - set_bearer_token(r, token) - r.json = {'description': 'token generated at ' + datetime.datetime.now().isoformat(), - 'password': admin_password - } - return send_request(session, r) - -def exit_fail(msg): - print(msg, file=sys.stderr) - exit(1) - -def main(): - init_session() - print('This script generates a token that authorizes calls to Wire\'s SCIM endpoints.\n') - print('Please enter the login credentials of a user that has role "owner" or "admin".') - ADMIN_EMAIL=input("Email: ") or exit_fail('Please provide an email.') - ADMIN_PASSWORD=getpass.getpass('Password: ') or exit_fail('Please provide password.') - bearer_token = create_bearer(ADMIN_EMAIL, ADMIN_PASSWORD) - scim_token = create_scim_token(ADMIN_PASSWORD, bearer_token['access_token']) - print('Wire SCIM Token: ' + scim_token['token']) - print('The token will be valid until you generate a new token for this user.') - -if __name__ == '__main__': - main() -```