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.

Sign up for GitHub

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

Jump to bottom

Publish IPIPs to specs.ipfs.tech #385

Merged
merged 4 commits into from
May 9, 2023
Merged

Publish IPIPs to specs.ipfs.tech #385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
00cfe45
docs: move ipips and ipip process
hacdias Mar 17, 2023
4cc2aea
docs: add moving placeholders
hacdias Mar 17, 2023
9388d0f
docs: editorial fixes to ipips
hacdias Mar 17, 2023
32740aa
fix: template title
hacdias May 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/CODEOWNERS
View file
Open in desktop
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,11 @@

# global IPIP
IPIP/ @ipfs/specs-stewards
src/ipips/ @ipfs/specs-stewards

# Selected Spec Stewards can be defined below to be automatically requested for
# review when someone opens a pull request that modifies area of their
# interest.

http-gateways/ @lidel
http-gateways/ @lidel
src/http-gateways/ @lidel
69 changes: 1 addition & 68 deletions IPIP/0000-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,68 +1 @@
# IPIP-0: InterPlanetary Improvement Proposal Template

<!-- IPIP number should match its pull request number. After you open a PR,
please update title and include anqabbreviated title in the filename too:
`0000-draft-title-abbrev.md`. -->

- Start Date: YYYY-MM-DD
- Related Issues:
- (add links here)

## Summary

<!--One paragraph explanation of the IPIP.-->
This is the suggested template for new IPIPs.

## Motivation

AKA Problem Statement

Clearly explain why the existing protocol specification is inadequate
to address the problem that the IPIP solves.

## Detailed design

AKA Solution Proposal

Describe the proposed solution and list all changes made to the specs repository.

The resulting specification should be detailed enough to allow competing,
interoperable implementations.

When modifying an existing specification file, this section should provide a
summary of changes. When adding new specification files, list all of them.

## Test fixtures

List relevant CIDs. Describe how implementations can use them to determine
specification compliance. This section can be skipped if IPIP does not deal
with the way IPFS handles content-addressed data, or the modified specification
file already includes this information.

## Design rationale

The rationale fleshes out the specification by describing what motivated
the design and why particular design decisions were made.

Provide evidence of rough consensus and working code within the community,
and discuss important objections or concerns raised during discussion.

### User benefit

How will end users benefit from this work?

### Compatibility

Explain the upgrade considerations for existing implementations.

### Security

Explain the security implications/considerations relevant to the proposed change.

### Alternatives

Describe alternate designs that were considered and related work.

### Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
Moved to [../ipip-template.md].
156 changes: 1 addition & 155 deletions IPIP/0001-lightweight-improvement-proposal-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,157 +1,3 @@
# IPIP 0001: Lightweight Improvement Process for IPFS Specifications

- Start Date: 2022-06-10
- Related Issues:
- [ipfs/specs/issues/286](https://github.com/ipfs/specs/issues/286)

## Summary

This _InterPlanetary Improvement Proposal_ (IPIP) introduces a lightweight
"request for comments/change" process for the IPFS specifications
[repository][1].

[1]: https://github.com/ipfs/specs/

## Motivation

Today, protocol design discussions often take place in a repository of an IPFS
implementation. These conversations are unintentionally obscured from the useful input of [Specs Stewards], other
implementations, service operators and the wider IPFS Community.

The IPFS Project needs a mechanism for proposing and evaluating specification
improvements that are not tied to a specific programming language
or implementation of IPFS.

## Detailed design

Adopt an informal IPIP process for the [ipfs/specs][1] repository, providing a
minimal structure for opening, reviewing, and merging specification changes.

The purpose of IPIP documents is to **document motivation** behind the change
applied to the spec. **IPIP is not to be the spec itself**.

To illustrate:
- In order to understand how (hypothetical) WebDAV Gateway works, one would
read contents of specs in `ipfs/specs/WEBDAV_GATEWAY.md`.
- IPIP in `ipfs/specs/IPIP/000N-webdav-gateway.md` would only include
**Motivation** and explainer why certain design decisions were made at a
certain point in time. Initial `IPIP/000N-webdav-gateway.md` would explain
why we added WebDAV spec in the first place.
- If we realize the spec has a bug, we will evaluate the impact: adding more
details, test vectors, and editorials/cosmetics can be fixed without IPIP.
- Things that could cause an interop issues require a PR with fix and IPIP in
`ipfs/specs/IPIP/000M-webdav-fix-for-foo.md` explaining why we make the
breaking spec change, compatibility/migration considerations etc.

### IPIP Lifecycle

Up-to-date process and IPIP lifecycle will be published in [`ipfs/specs/IPIP_PROCESS.md`](../IPIP_PROCESS.md).

<details>
<summary>Click to expand the initial (historical) flow</summary>

### Opening an improvement proposal (IPIP)

Changes to IPFS specifications can be proposed by opening a Git pull-request
(PR) against the `ipfs/specs` repository.

In addition to specification changes, such PR must include a short **IPIP
document** based on the template in [`ipfs/specs/IPIP/0000-template.md`](./0000-template.md).

When a new specification file is added to the repo, it should be based on
the template at [`ipfs/specs/template.md`](../template.md).

### Reviewing IPIPs

[Specs Stewards] will review new IPIP PRs during periodical (best-effort) triage.

IPFS Community is encouraged to participate in the review process.

IPIP can be either:
- merged,
- rejected (PR close without merging),
- deferred (converting PR back to a draft).

The final decision belongs to [Specs Stewards].

### Merging IPIPs

PR with a IPIP can be merged only after two [Specs Stewards] approve it and
there are no objections from other Stewards.

IPIP number is assigned before the PR merge.

IPIP author and two approving [Specs Stewards] are added to `CODEOWNERS` file
to be automatically asked to review any future changes to files added or
modified by the IPIP.

</details>


### Long-term plan

[Specs Stewards] will adjust the process based on usage patterns.

## Design rationale

We want to empower IPFS community members and implementers with the ability to propose
changes in a well-known way, without introducing much overhead.

Guiding principles:
- No new tooling
- Reuse Markdown, Git, and existing PR review process
- Convention over Byzantine process
- Proposing a new IPIP should have low cognitive overhead, allowing us to
focus on specs
- Reuse existing GitHub developer accounts and reputation attached to them
- One should be able to create a valid IPIP without reading a long explainer
like this one. Looking at past IPIPs, and then copying a template and
opening a PR with the proposal should be more than enough.

### User benefit

End users will indirectly benefit from a healthy IPIP process being in place:

- IPFS community members will be able to use IPIP drafts for evaluating ideas
before investing time into building new things.
- The bar for creating a brand new IPFS implementation will be lowered, and
existing implementations will be able to propose improvements for others to
adopt. This removes the soft vendor lock-in present when the oldest
implementation is considered as the reference standard and source of truth.
- IPFS implementers will have a better understanding of why certain design
decisions were made, and have both historical context and language-agnostic
specifications with test fixtures ready for use in their project, ensuring
a high level of interoperability.
- More eyes looking at specifications will improve overall quality over time.

As a result, IPFS will become easier to implement, useful in more contexts,
and benefit more people.

### Compatibility

Existing contents of [ipfs/specs][1] repository act as the initial state
against which IPIP PRs can be opened.

### Security

Existing Git-based review infrastructure, user accounts and reputation
system will be reused.

Merging IPIP will require approval from two [Specs Stewards].

### Alternatives

- Maintaining the status quo (no IPIP process) is not acceptable, as we want to
move specification discussions away from repositories of specific
implementations. We need a mechanism for discussing improvements that is not
tied to specific implementation or language.
- Creating more elaborate IPIP process. This comes with increased overhead and
risk. Introducing a complex process requires deeper understanding of
community needs and pitfalls of preexisting processes, and since we don't
have any process in place, starting light, limits the risk.

### Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

[Specs Stewards]: https://github.com/orgs/ipfs/teams/specs-stewards/members
Moved to https://specs.ipfs.tech/ipips/ipip-0001/
77 changes: 1 addition & 76 deletions IPIP/0002-gateway-redirects-file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,3 @@
# IPIP 0002: _redirects File Support on Web Gateways

- Start Date: 2022-06-15
- Related Issues:
- [ipfs/specs/issues/257](https://github.com/ipfs/specs/issues/257)
- [ipfs/kubo/pull/8890](https://github.com/ipfs/kubo/pull/8890)
- [ipfs-docs/pull/1275](https://github.com/ipfs/ipfs-docs/pull/1275)

## Summary

Provide support for URL redirects and rewrites for web sites hosted on Subdomain or DNSLink Gateways, thus enabling support for [single-page applications (SPAs)](https://en.wikipedia.org/wiki/Single-page_application), and avoiding [link rot](https://en.wikipedia.org/wiki/Link_rot) when moving to IPFS-backed hosting.

## Motivation

Web sites often need to redirect from one URL to another, for example, to change the appearance of a URL, to change where content is located without breaking existing links (see [Cool URIs don't change](https://www.w3.org/Provider/Style/URI), [link rot](https://en.wikipedia.org/wiki/Link_rot)), to redirect invalid URLs to a pretty 404 page, or to enable URL rewriting.
URL rewriting in particular is a critical feature for hosting SPAs, allowing routing logic to be handled by front end code. SPA support is the primary impetus for this RFC.

Currently the only way to handle URL redirects or rewrites is with additional software such as NGINX sitting in front of the Gateway. This software introduces operational complexity and decreases the uniformity of experience when navigating to content hosted on a Gateway, thus decreasing the value proposition of hosting web sites in IPFS.

This IPIP proposes the introduction of redirect support for content hosted on Subdomain or DNSLink Gateways, configured via a `_redirects` file residing underneath the root CID of the web site.

## Detailed design

Allow developers to configure redirect support by adding redirect rules to a file named `_redirects` stored underneath the root CID of their web site.
The format for this file is similar to those of [Netlify](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) and [Cloudflare Pages](https://developers.cloudflare.com/pages/platform/redirects) but only supporting a subset of their functionality.

The format for the file is `from to [status]`.

- `from` - specifies the path to intercept (can include placeholders and a trailing splat)
- `to` - specifies the path or URL to redirect to (can include placeholders or splat matched in `from`)
- `status` - optional [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) (301 if not specified)

Rules in the file are evaluated top to bottom.

For performance reasons this proposal does not include forced redirect support (i.e. redirect rules that are evaluated even if the `from` path exists). In other word, redirect logic will be evaluated if and only if the requested path does not exist. If the requested path exists, we won't even check for the existence of the `_redirects` file.

If a `_redirects` file exists but is unable to be processed, perhaps not even parsing correctly, errors will be returned to the user viewing the site via the Gateway.

The detailed specification is added in [`http-gateways/REDIRECTS_FILE.md`](../http-gateways/REDIRECTS_FILE.md).

### Test fixtures

`QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4`

See spec for testing details.

## Design rationale

Popular services today such as [Netlify](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) and [Cloudflare Pages](https://developers.cloudflare.com/pages/platform/redirects) allow developers to configure redirect support
using a `_redirects` file hosted at the top level of the web site. While we do not intend to provide all of the same functionality, it seems desirable to use a similar approach to provide a meaningful subset of the functionality offered by these services.

- The format is simple and low on syntax
- Many developers are already familiar with this file name and format
- Using a text file for configuration enables developers to make changes without using other IPFS tools
- The configuration can be easily versioned in both version control systems and IPFS by virtue of the resulting change to the root CID for the content

### User benefit

Provides general URL redirect and rewrite support, which enables three important features:
1. Developers will be able to host single-page applications in IPFS.
2. Same configuration file used for setting up pretty 404 pages.
3. The cost of switching hosting of an existing website to IPFS is lowered by making it possible to keep all legacy URLs working.

### Compatibility

If by some chance developers are already hosting sites that contain a `_redirects` file that does something else, they may need to update the contents of the file to match the new functionality. Errors returned to the user due to parsing errors will guide them regarding the required updates.

### Alternatives

- There was some discussion early on about a [manifest file](https://github.com/ipfs/specs/issues/257) that could be used to configure redirect support in addition to many other things. While the idea of a manifest file has merit, manifest files are much larger in scope and it became challenging to reach agreement on functionality to include.
There is already a large need for redirect support for SPAs, and this proposal allows us to provide that critical functionality without being hampered by further design discussion around manifest files.
In addition, similar to how Netlify allows redirect support to be configured in either a `_redirects` file or a more general [configuration file](https://docs.netlify.com/configure-builds/file-based-configuration/#redirects), there is nothing precluding IPFS from allowing developers to configure redirect support in an app manifest later on.
- There was some discussion with the [n0](https://github.com/n0-computer/) team about potential ways to improve the performance of retrieving metadata such as redirect rules, possibly including it as metadata with the root CID such that it would be included with the request for the CID to begin with.
I believe the performance concerns are alleviated by not providing forced redirect support, and looking for `_redirects` only if the DAG is missing a requested path. Never the less, if a more generic metadata facility were to be introduced in the future, it may make sense to reconsider how redirect rules are specified.

### Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
Moved to https://specs.ipfs.tech/ipips/ipip-0002/
Loading