Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add heuristic to determine resource type #160

Merged
merged 7 commits into from Jun 9, 2020
Merged

Conversation

csarven
Copy link
Member

@csarven csarven commented Apr 3, 2020

Criteria for servers to apply heuristics to determine a request's resource type. Based on consensus at #128 (comment)

@csarven csarven changed the title Editors draft extended Add heuristic to determine resource type May 12, 2020
Copy link
Contributor

@RubenVerborgh RubenVerborgh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clear for me.

Perhaps a suggestion for the first column format: "String ending in a slash (e.g., foo/)" such that it is explicit what to generalize on.

<tr>
<td><code>foo/</code></td>
<td>`Link` header other than container type.</td>
<td>Create a resource with `foo` appended to the request-URI, check for
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This exception I find very weird. I don't think we should derive anything from non-recognized Link headers. I.e., all no and other cases should be identical for me.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's indeed what's intended. What's derived is that it is a non-Container resource. Slug will be ignored in this case. Would rephrasing help?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My interpretation of what written seems to be correct (so writing is ok); but I don't understand why from an unknown header can be derived the resource is non-Container. I don't think we should derive that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's recognised is "ldp:Container or a specialisation" (ldp:BasicContainer - as that's the only one currently required) as the "container type". I used "other than container type" to express their absence. Open to rephrasing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah okay, so only Link header values with a type link relation are included then? Or do we really mean all Link header values?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only the existence of Link with rel=type LDPC or LDP-BC is checked.

Note the check in prior row says "Link header with ldp:Container or a specialisation." - We are really talking about rel=type here.

So we can just mention the actual relation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I would make it clear that it is a rel=type header value. Then I have no further objections.

We could perhaps call them "indicated types" or so, and then declare above the table how those indicated types are extracted from Link. No strong opinion.

Copy link
Member Author

@csarven csarven May 12, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used "or a specialisation" instead of ldp:BasicContainer figuring that if other container types are supported in the future, they will also follow the slash semantics. If server gets Link rel=type LDP-DC, it will create a container resource with trailing slash.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All fine with me, my issue/misunderstanding was in the phrasing of "Link header other than container type."

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about e40d685 for this draft?

main/resource-access.bs Outdated Show resolved Hide resolved
@csarven
Copy link
Member Author

csarven commented May 12, 2020

Good suggestions. Will this work for now: 3207529 ?

@RubenVerborgh
Copy link
Contributor

Yeah. (Maybe "slashes" for grammar? But I don't mind.)

@RubenVerborgh RubenVerborgh self-requested a review May 12, 2020 15:26
Copy link
Contributor

@RubenVerborgh RubenVerborgh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good stuff!

Copy link
Member

@justinwb justinwb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few comments inline. Also wondering if it is worth mentioning whether/how different request methods may or may not affect the heuristic and any associated results?

main/resource-access.bs Outdated Show resolved Hide resolved

Servers MUST apply the following heuristics to determine a request's resource
type
[[Source](https://github.com/solid/specification/issues/128#issuecomment-573033297)].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider explaining under what circumstances the server needs to fall back to this heuristic approach. (i.e. when the client does not specify an interaction model)?

Copy link
Member

@dmitrizagidulin dmitrizagidulin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 from me. (Although I'd love to see container and resource names changed from foo/ to example/).

@csarven
Copy link
Member Author

csarven commented May 29, 2020

[exit rabbit-holes]

I've revisited this issue from the requirements. Some initial considerations:

  • Based on slash semantics, a container's URI ends with /.

  • LDP-BC is the only container interaction required from Solid servers.

  • The difference between the initial "Link header setting some other LDP interaction model" and the current "Link header without a rel="type" targeting a valid LDP container type."

  • The Slug header can introduce conformance variability. The degree of variance and what's acceptable needs to be weighed.

  • To what extent shared slashes should be applied to slugtext, if at all, partial (eg. excluding nested containers), or in full?


Most relevant functional requirements (F1 is borrowed from LDP-UCR):

  • F1.1: The system shall provide the ability to create resources within a container.
  • F1.2: The system shall provide the ability to create containers for composing resources.
  • F1.3: The system shall provide the ability to create nested containers.
  • F2.1: The system shall provide the ability to use client's preferred naming.
  • F2.2: The system shall provide the ability to use server's preferred naming.

Non-functional requirement (along the lines of LDP's NF2.3):

  • NF1: The system shall support consistent global naming for resource types.

In context of creating resources:

PUT and PATCH can be used to meet F1 and F2.1 but not F2.2.

POST can meet F1 and F2 with different conformance configurations:

  • C1: Servers MUST allow creating new resources with a POST request to URI path ending / [F1].
  • C2: Servers MUST create a resource with URI path ending /{id} in container / [F1.1].
  • C3: Servers MUST create a container with URI path ending /{id}/ in container /:
  • C3.1: request including Link header with rel="type" targeting a valid LDP container type [F1.2].
  • C3.2.1: request including Slug header with slugtext using the shared slash semantics [F1.2, F1.3, F2.1].
  • C3.2.2: request including Slug header with undefined slugtext [F1.1, F2.1, F2.2].
Functional Requirements and Conformance Rules
F1.1 F1.2 F1.3 F2.1 F2.2
C1
C2
C3
C3.1
C3.2.1
C3.2.2??
✔: Passed ?: Cannot tell

Notes:

  • C1, C2, C3 are based on slash semantics.

  • C3.1 is compatible with LDP's interaction model for containers.

  • C3.1 using MUST and C3.2.1 using MUST will require servers to do a consistency check.

  • C3.2.1 using MUST for Slug and MUST for defined slugtext will meet F1.3 and F2.1 (but not F2.2)

  • C3.2.1 using MAY for Slug and MUST for defined slugtext would allow a client suggesting the name of a container with Slug: foo/ to create a container at one server meanwhile a non-container resource at another server. This conformance variance is generally best avoided but does not pose an issue for interoperability.

  • C3.2.2 meets F2.1 and F2.2 in a way that server can decide to integrate the suggestion.


Status check:

  • The original rough consensus in Clarify the heuristics to determine the interaction model if none is specified #128 (comment) was based on the idea that heuristics are based on all LDP interaction models. The Solid requirement to date is only loosely based on LDP's interaction model for containers, and more specifically, BasicContainer implementation is the only specialisation that's prescribed (re: hierarchical containment and slash semantics). Note for example the important transition from original rough consensus: "Link header setting some other LDP interaction model" to the updated text in PR: "Link header without a rel="type" targeting a valid LDP container type."

  • As in the note about C3.2.1 (MAY Slug, MUST defined slugtext..), there is an internal inconsistency - variability - in the rough consensus table in that Slug: foo/ without Link creates a container but where Slug is not observed or ignored, it will create a resource.

  • Taking a step back, there are questions that need more firm answers. Primarily to what extent should the heuristics influenced by slash semantics, and the possibility of Link and Slug headers being present?

  • We can simplify the heuristics or lean towards eliminating it. Some considerations:

    • by not prescribing C3.2.1 in order to meet F1.3 via POST. Or alternatively, C3.2.1 is limited to suggesting a container (as opposed to nested containers - which can potentially introduce security issues because of varying code paths in implementations).

    • if any level of compatibility with LDP interaction models is desired, C3.1 is needed and should at least observe a valid LDP container type (LDP-BC at this time).

    • Looking back at PUT and PATCH and that they can't meet F2.2, we need POST to meet F2.2. However, POST with C3.2.2 may eliminate that possibility and C3.2.1 will prevent F2.2.

    • We should put a pause on the possibility to create resources where effective request URI ends with /{id}. It entails that only POST to container / is of interest. So, taking on C3.1 (and not any possible LDP interaction model). Consistency check is not required.

My current preference is that we simplify the implementation as much as possible and I think the issues surrounding heuristics introduces a degree of complexity with of course some "benefits" that are not critical to meeting the functional requirements. Note #108 (comment) as an example where certain code paths are blocked but the requirements met by other conformance rules.

@csarven
Copy link
Member Author

csarven commented Jun 1, 2020

Focusing on F2.2:

POST request is required to meet F2.2 for URI path ending /.

Note: POST request to URI path ending /{id} will not address F2.2 because client ends up specifying the name (which is actually F2.1). It is hypothetically possible but this is an awkward way of going at it for POST which doesn't fit well with the rest of the setup. It is also neither a common practice or used in existing implementations.

F1.3 will not be prescribed for POST as it requires C3.2.1 as MUST and that consequently conflicts with F2.2.

Proposal:

  • C1 is used to meet F1.1 and F1.2.
  • C2 is used to meet F1.1.
  • C3 + C3.1 is used to meet F1.2.

Note: C3.2.2 can be prescribed as MAY but it will be used towards F2.1 instead.

If agreed, I can update the PR and follow up on the related issues. Open to go through alternatives if anyone would like.

Copy link
Member

@acoburn acoburn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

@csarven csarven added this to Drafting in Specification via automation Jun 2, 2020
@csarven csarven added this to the ~First Public Working Draft milestone Jun 2, 2020
Copy link
Member

@dmitrizagidulin dmitrizagidulin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

@justinwb
Copy link
Member

justinwb commented Jun 8, 2020

If agreed, I can update the PR and follow up on the related issues. Open to go through alternatives if anyone would like.

👍 from me to proceed with updating PR

@csarven csarven merged commit 88baa6e into master Jun 9, 2020
Specification automation moved this from Drafting to Done Jun 9, 2020
@csarven
Copy link
Member Author

csarven commented Jun 9, 2020

Updated PR c1aac42 based on #160 (comment) . Will continue to add related criteria in new PRs. Thanks all!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Done
Specification
  
Done
Development

Successfully merging this pull request may close these issues.

None yet

5 participants