Merge branch 'main' into ipip-0518-https-urls-in-routing-v1

Author: lidel

.github/workflows/deploy.yml

@@ -8,6 +8,7 @@ name: Deploy
 
 # Explicitly declare permissions
 permissions:
+  actions: read
   contents: read
   pull-requests: write
   statuses: write
@@ -26,6 +27,8 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       cid: ${{ steps.deploy.outputs.cid }}
+    environment:
+      name: 'ipfs-publish'
     steps:
       - name: Download build artifact
         uses: actions/download-artifact@v4
@@ -48,18 +51,23 @@ jobs:
           #TODO pinata-jwt-token: ${{ secrets.PINATA_JWT_TOKEN }}
           github-token: ${{ github.token }}
 
-      # TODO: right now, DNSLink is controlled by Fleek, and we use ipfs/ipfs-deploy-action for PR previews
-      #- name: Update DNSLink
-      #  if: github.event.workflow_run.head_branch == 'main'
-      #  uses: ipfs/dnslink-action@v0.1
-      #  with:
-      #    cid: ${{ steps.deploy.outputs.cid }}
-      #    dnslink_domain: 'specs.ipfs.tech'
-      #    cf_record_id: ${{ secrets.CF_RECORD_ID }}
-      #    cf_zone_id: ${{ secrets.CF_ZONE_ID }}
-      #    cf_auth_token: ${{ secrets.CF_AUTH_TOKEN }}
-      #    github_token: ${{ github.token }}
-      #    set_github_status: true
+  dnslink-update:
+    runs-on: ubuntu-latest
+    needs: deploy-ipfs
+    if: github.event.workflow_run.head_branch == 'main'
+    environment:
+      name: 'cf-dnslink'
+      url: "https://specs-ipfs-tech.ipns.inbrowser.link/"
+    steps:
+      - name: Update DNSLink
+        uses: ipshipyard/dnslink-action@v1
+        with:
+          cid: ${{ needs.deploy-ipfs.outputs.cid }}
+          dnslink_domain: 'specs-ipfs-tech.dnslinks.ipshipyard.tech'
+          cf_zone_id: ${{ secrets.CF_DNS_ZONE_ID }}
+          cf_auth_token: ${{ secrets.CF_DNS_AUTH_TOKEN }}
+          github_token: ${{ github.token }}
+          set_github_status: true
 
   deploy-gh-pages:
     if: |

.gitignore

@@ -1,3 +1,4 @@
 out/
 node_modules/
 super-linter.log
+node_modules/

ARCHITECTURE.md

@@ -1,9 +1,9 @@
-# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Architecture Overview
+# ![status: deprecated](https://img.shields.io/badge/status-deprecated-red.svg?style=flat-square) IPFS Architecture Overview
 
 > [!NOTE]
 > This document contains historical notes about IPFS architecture from ~2015. For current specifications, please refer to https://specs.ipfs.tech/
 
-**Authors(s)**:
+**Author(s)**:
 - [Juan Benet](https://github.com/jbenet)
 - [David Dias](https://github.com/daviddias)
 
@@ -12,20 +12,20 @@
 
 * * *
 
-**Abstract**
+## Abstract
 
 This spec document defines the IPFS protocol stack, the subsystems, the interfaces, and how it all fits together. It delegates non-interface details to other specs as much as possible. This is meant as a top-level view of the protocol and how the system fits together.
 
 Note, this document is not meant to be an introduction of the concepts in IPFS and is not recommended as a first pass to understanding how IPFS works. For that, please refer to the [IPFS paper](https://github.com/ipfs/papers/raw/master/ipfs-cap2pfs/ipfs-p2p-file-system.pdf).
 
 # Table of Contents
 
-- 1. IPFS and the Merkle DAG
-- 2. Nodes and Network Model
-- 3. The Stack
-- 4. Applications and data structures -- on top of IPFS
-- 5. Lifetime of fetching an object
-- 6. IPFS User Interfaces
+1. IPFS and the Merkle DAG
+1. Nodes and Network Model
+1. The Stack
+1. Applications and data structures -- on top of IPFS
+1. Lifetime of fetching an object
+1. IPFS User Interfaces
 
 # 1. IPFS and the Merkle DAG
 
@@ -48,7 +48,6 @@ In turn, these yield properties for the system as a whole:
 
 IPFS is a stack of network protocols that organize agent networks to create, publish, distribute, serve, and download merkledags. It is the authenticated, decentralized, permanent web.
 
-
 # 2. Nodes and Network Model
 
 The IPFS network uses PKI based identity. An "ipfs node" is a program that can find, publish, and replicate merkledag objects. Its identity is defined by a private key. Specifically:
@@ -72,7 +71,6 @@ sha2-512
 sha3
 ```
 
-
 # 3. The Stack
 
 IPFS has a stack of modular protocols. Each layer may have multiple implementations, all in different modules. This spec will only address the interfaces between the layers, and briefly mention possible implementations. Details are left to the other specs.
@@ -85,7 +83,7 @@ IPFS has five layers:
 - **routing** - locating peers and objects
 - **network** - establishing connections between peers
 
-![](img/ipfs-stack.png)
+![IPFS protocol stack](img/ipfs-stack.png)
 
 These are briefly described bottom-up.
 
@@ -165,7 +163,7 @@ The merkledag is enough to resolve paths:
 
 See more in the [path resolution spec](https://github.com/ipld/specs/blob/master/data-model-layer/paths.md).
 
-![](img/ipfs-resolve/ipfs-resolve.gif)
+![IPFS path resolution](img/ipfs-resolve/ipfs-resolve.gif)
 
 ## 3.5 Naming -- PKI namespace and mutable pointers
 
@@ -196,7 +194,7 @@ The unix filesystem abstractions -- files and directories -- are the main way pe
 
 See more in the [unixfs spec](https://github.com/ipfs/specs/blob/master/UNIXFS.md).
 
-## 5. Lifetime of fetching an object.
+## 5. Lifetime of fetching an object
 
 Suppose we ask an IPFS node to retrieve
 
@@ -225,7 +223,7 @@ IPFS is not just a protocol. It is also a toolset. IPFS implementations include
 
 * * *
 
-# WIP Stack Dump:
+# WIP Stack Dump
 
 - How the layers fit together
 - How they call on each other

src/bitswap-protocol.md

@@ -29,7 +29,7 @@ editors:
       name: Protocol Labs
       url: https://protocol.ai/
 tags: ['exchange', 'routing']
-order: 1
+order: 2
 ---
 
 Bitswap is a libp2p data exchange protocol for sending and receiving content

src/http-gateways/dnslink-gateway.md

@@ -69,7 +69,9 @@ Implementations MUST ensure DNSLink resolution is safe and correct:
   recursion limit (e.g. 32) and HTTP 400 Bad Request error MUST be returned
   when the limit is reached.
 
-**Example: resolving an advanced DNSLink chain**
+:::note
+
+Example: resolving an advanced DNSLink chain
 
 To illustrate, given DNSLink records:
 
@@ -85,6 +87,8 @@ content path:
 3. Resolving DNSlink at `b.example.net` replaces `/ipns/b.example.net` with `/ipfs/bafy…qy3k/path-c`
 4. The immutable content path is `/ipfs/bafy…qy3k/path-c/path-b/path-a`
 
+:::
+
 # HTTP Response
 
 Same as "HTTP Response" of :cite[path-gateway].

src/http-gateways/path-gateway.md

@@ -4,15 +4,23 @@ description: >
   The comprehensive low-level HTTP Gateway enables the integration of IPFS
   resources into the HTTP stack through /ipfs and /ipns namespaces, supporting
   both deserialized and verifiable response types.
-date: 2024-04-17
+date: 2025-10-13
 maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
     url: https://lidel.org/
     affiliation:
-      name: Protocol Labs
-      url: https://protocol.ai/
+      name: Shipyard
+      url: https://ipshipyard.com
+former_editors:
+  - name: Henrique Dias
+    github: hacdias
+    url: https://hacdias.com/
+    affiliation:
+      name: Shipyard
+      url: https://ipshipyard.com
+thanks:
   - name: Adrian Lanzafame
     github: lanzafame
     affiliation:
@@ -28,12 +36,6 @@ editors:
     affiliation:
       name: Protocol Labs
       url: https://protocol.ai/
-  - name: Henrique Dias
-    github: hacdias
-    url: https://hacdias.com/
-    affiliation:
-      name: Protocol Labs
-      url: https://protocol.ai/
 xref:
   - rfc3986
   - trustless-gateway
@@ -332,6 +334,11 @@ Gateways MUST use 404 to signal that content is not available, particularly
 when the gateway is [non recursive](#recursive-vs-non-recursive-gateways), and only provides access to a known
 dataset, so that it can assess that the requested content is not part of it.
 
+NOTE: Gateways MUST return 404 for missing root blocks. However, for streaming
+responses (such as CAR), once HTTP 200 OK status is sent, gateways cannot
+change it. If a child block is missing during streaming, the gateway SHOULD
+terminate the stream. Clients MUST verify response completeness.
+
 ### `410` Gone
 
 Error to indicate that request was formally correct, but this specific Gateway
@@ -639,6 +646,10 @@ Indicates the original, requested content path before any path resolution and tr
 
 Example: `X-Ipfs-Path: /ipns/k2..ul6/subdir/file.txt`
 
+This header SHOULD be returned with deserialized responses.
+Implementations MAY omit it with trustless response types
+(`application/vnd.ipld.raw` and `application/vnd.ipld.car`).
+
 ### `X-Ipfs-Roots` (response header)
 
 Used for HTTP caching.
@@ -668,6 +679,15 @@ NOTE: while the first CID will change every time any article is changed,
 the last root (responsible for specific article or a subdirectory) may not
 change at all, allowing for smarter caching beyond what standard Etag offers.
 
+This header SHOULD be returned with deserialized responses.
+Implementations MAY omit it with trustless response types
+(`application/vnd.ipld.raw` and `application/vnd.ipld.car`).
+
+NOTE: Gateways that stream responses (e.g., CAR) without pre-resolving the
+entire path MAY only include the root CID for simple `/ipfs/{cid}` requests, or
+MAY omit this header for path requests where intermediate CIDs are not known
+when headers are sent.
+
 ### `X-Content-Type-Options` (response header)
 
 Optional, present in certain response types: