Docs: Delegation #956
No reviewers
Labels
No labels
Android
CS::needs customer feedback
CS::needs follow up
CS::needs on prem installation
CS::waiting
Chrome
Design:: Ready
Design:: in progress
Design::UX
E2EE
Edge
Firefox
GDPR
Iteration 13 IM
Linux
MacOS
Need::Discussion
Need::Steps to reproduce
Need::Upstream fix
Needs:: Planning
Needs::Dev-Team
Needs::More information
Needs::Priority
Needs::Product
Needs::Refinement
Needs::Severity
Priority::1-Critical
Priority::2-Max
Priority::3-Impending
Priority::4-High
Priority::5-Medium
Priority::6-Low
Priority::7-None
Progress::Backlog
Progress::Review
Progress::Started
Progress::Testing
Progress::Triage
Progress::Waiting
Reporter::Sentry
Safari
Target::Community
Target::Customer
Target::Internal
Target::PoC
Target::Security
Team:Customer-Success
Team:Design
Team:Infrastructure
Team:Instant-Messaging
Team:Product
Team:Workflows
Type::Bug
Type::Design
Type::Documentation
Type::Feature
Type::Improvement
Type::Support
Type::Tests
Windows
blocked
blocked-by-spec
cla-signed
conduit
contribution::advanced
contribution::easy
contribution::help needed
from::review
iOS
p::ti-tenant
performance
product::triage
proposal
refactor
release-blocker
s: dart_openapi_codegen
s::Famedly-Patient
s::Org-Directory
s::Passport-Generator
s::Requeuest
s:CRM
s:Famedly-App
s:Famedly-Web
s:Fhiroxide
s:Fhiroxide-cli
s:Fhiroxide-client
s:Fhirs
s:Hedwig
s:LISA
s:Matrix-Dart-SDK
s:Role-Manager
s:Synapse
s:User-Directory
s:WFS-Matrix
s:Workflow Engine
s:dtls
s:famedly-error
s:fcm-shared-isolate
s:matrix-api-lite
s:multiple-tab-detector
s:native-imaging
severity::1
severity::2
severity::3
severity::4
technical-debt
voip
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference: Matthias/conduit#956
Loading…
Reference in a new issue
No description provided.
Delete branch "docs-delegation"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Changes:
I would not use the wording "server name" in this paragraph, because that is what Conduit uses to refer to the name of the server it considers its own (see the config example).
So, in away it is actually the other way around: To use the domain as the server name instead of the hostname Conduit is reachable with (for example
conduit.example.com
), do delegation as described below etc. etc.As per your config example, "server name" would equal
example.com
in this context. We would use delegation to have Conduit listen onsomethingotherthanexample.com
. Therefore, the sentence seems right to me.Could you please read it one more time and confirm that you still see a problem?
I completely understand what you are trying to say. Maybe the source of the confusion is that Conduit doesn't really "listen" on a domain but only allows for (the hosting of) s single server name. IMO it might be better to say: Delegation can also be used to have Conduit be reachable on a hostname or even domain different from your (configured) server name.
I think it's good to reiterate/reinforce that what's behind the colon is what we call the server name which is what you have written in the configuration. I have found this to be a common source of confusion.
Note that this some something you mention later with "By using delegation, you can host Conduit [...]" and this would bring this a bit to the front?
(Feel free to ignore this comment though, if you do not agree.)
Suggestion: Delegation can also be used to host Conduit on a domain different from your server name...
or: A further use of delegation is to host Conduit on a domain different from your server name...
This also means removing or at least changing the last sentence to avoid repetition.
Any idea where you got this from?
This is simply serving a JSON file. Why do we need to allow POST, PUT, DELETE, and OPTIONS HTTP methods? I don't see this anywhere in Synapse delegation documentation. I am only aware of
Access-Control-Allow-Origin *
andCross-Origin-Resource-Policy cross-origin
(which is missing here by the way) being required for the/client
file at minimum.Same thing as my review above^
Missing
Cross-Origin-Resource-Policy cross-origin
and unsure what the purpose ofAccess-Control-Allow-Headers
andAccess-Control-Allow-Methods
are for.I am unsure as to why, but it is recommended by the specification:
"Servers hosting the .well-known JSON file SHOULD offer CORS headers, as per the CORS section in this specification."
Closing as duplicate. A possible discussion should only happen in one place at the same time.
Talked about it in the Conduit chat and I'm going to assume this is really just a misleading or confusing spec issue that Synapse docs deviate from to make it even more confusing.
I've used plenty of mobile and desktop clients (FluffyChat, Nheko, Element, ElementX, Cinny, etc) with just ACAO * and CORP cross-origin with zero issues, but supposedly
OPTIONS
method is necessary for JavaScript-based clients (?). I definitely know for a fact most of this is really not necessary, but I'm fine with leaving it as is either way.This sort of sidesteps the awkward fact that one can’t easily return
.json
with200
on httpd as one can with nginx and Caddy.I don’t believe the current example really works. The only way to bring this in line with your other examples I can think of is to set the headers here, but add instructions for creating the
.json
file manually.What would you expect it to be done here?
This example was not working, therefore, I removed it.
I tried adding a new working one, but given my lack of experience with Apache webservers, I eventually decided to leave this task to someone with more knowledge of httpd.
mod_lua
seems to fit the bill. You might have a go at it, or we can leave this for another PR. If someone has a better solution, I’d love to hear it too.https://gist.github.com/james2doyle/f09b0e159bb30836e593
mentioned in merge request !500
changed this line in version 2 of the diff
added 3 commits
a059c5bc
- Added section about delegationCompare with previous version
resolved all threads
After this gets merged, I’m happy to redo the
httpd
snippet in a follow-up PR as discussed above.Sorry for chiming in. I use caddy, and I noticed you added an example.
While certainly working, I think it could be better:
As a side note, I prefer redirecting
example.com
's.well-known/matrix/*
like this:And the actual JSON response and header controls go to the subdomain's file
mentioned in issue #378
changed this line in version 3 of the diff
added 2 commits
1d89b211
- Documentation on how to set up delegation with .well-knownb29dc440
- Remove superseded sectionsCompare with previous version
Thank you for your suggestions. The example now uses
handle_path
.Your question about
Access-Control-Allow-Methods
has been answered earlier already.resolved all threads
because otherwise "Setting up the Reverse Proxy" would be on the same level and thus an empty section
thus, this should probably become
I would suggest to just referring to the synapse docs for an explanation of the delegation methods, as they are somewhat the canonical source for info on this.
Thanks for filling this documentation gap <3
I have left a few small suggestions, but other than that I'm happy.
I strongly disagree, but I am curious to hear the reason for your suggestion. IMHO, it is simply counterproductive to increase the number of clicks a user has to make to understand what is happening.
Furthermore, we should orient after the specs, not the synapse documentation. Using the latter as a basis for this documentation is a great way to copy mistakes or some custom synapse setting.
This is a bit wordy and introduces repetitions.
Because they have read the section about delegation, they know how it works. Blankly stating that they (probably) only need 443 is unnecessary and could lead to confusion as to why they need this port and not some other. We should aim to inform about possible configurations, not decide for one and ignore others.
I will not apply this suggestion.
Could it be more useful to set "Setting up the Reverse Proxy" as a top level header?
mentioned in merge request !556
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.Merge
Merge the changes and update on Forgejo.