To ensure metadata is always stored, the CID returned from `addFile` will resolve to a directory.

The `path` property is now required of the import candidate passed to `addFile`, if it's not necessary to store a path as part of a file, use `addBytes` or `addByteStream`.

Since `urlSource` returns a `{ content, path }` candidate, it can be used with `addFile`.

To import directly from a URL without a path, a `urlByteStream` function has been added for use with `addByteStream`.

Fixes #707

BREAKING CHANGE: addFile requires the import candidate to have `path` and `content` properties and the returned CID will always resolve to a directory

---------

Co-authored-by: Daniel N <2color@users.noreply.github.com>

Splits the unixfs/mfs stat command return types into two types - "regular" stats (these only return stats available on the root node of the DAG) and "extended" - these collect stats from the DAG, potentially going to the network to fetch missing blocks.

There are separate simple and extended types for files and dirs, but raw/leaf nodes only get one type since there are never any nodes linked to from them.

As a bonus we can now calculate the size of directories correctly, (as the combination of all child files/directories), assuming all blocks are present in the blockstore or fetchable from the network.

Fixes #580

BREAKING CHANGE: Fields that would involve DAG traversal have been removed from the output of `fs.stat` - pass the `extended` option to have them returned

---------

Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com>
Co-authored-by: Daniel N <2color@users.noreply.github.com>

* feat: allow opting out of provider shuffle in HTTPGatewayRouter

* fix: parameter naming in HTTPGatewayRouterInit

Ensure the promise returned from `.get` on a session is rejected if the passed abort signal fires.

Fixes #775

---------

Co-authored-by: Alex Potsides <alex@achingbrain.net>

* test: ensure dag-scope=all car can be generated

* refactor: check filter before blockstore

* test: add test for subgraph dag-scope=all

* fix: dag-scope=all returns proper car for subdag root

* test: move dag-scope tests to their own file

* feat: support dag walking hints

* feat: implement dag-scope entity and block

* test: add dag-scope tests

* chore: some test cleanup

* chore: some cleanup

* refactor: strategy pattern and knownDagPath verification

* chore: Update packages/car/test/fixtures/car-equals.ts

* chore: fix logger use

* chore: remove unnecessary helper function

* refactor: move known path to strategy

* chore: normalize initial processBlock call

* refactor: move options validation to its own function

* chore: fix cspell errors

* Update packages/car/src/types.ts

Co-authored-by: Alex Potsides <alex@achingbrain.net>

* refactor: cleanup dagscope type

* fix: don't use defaultLogger

* fix: consistent returnType for getNextCidStrategy

* fix: dont require blocks to be in blockstore

* chore: libp2p-logger is not prod dep

* chore: fix cspell errors

* chore: correct `block` entity-type description

Co-authored-by: Alex Potsides <alex@achingbrain.net>

* chore: remove BlockNotFoundError

* chore: move exported types back to index.ts

* chore: use array for standard strategy roots

* refactor: use exporter/traversal API

* test: fix some dag-scope tests

* fix: dag-scope tests pass

* chore: some debugging

* fix: multi root cars work again

* chore: some fixes

* chore: fix spellcheck

* chore: minor cleanup

* chore: fix spell-check

* chore: remove unnecessary logging

* chore: cleanup code and comments

* chore: remove logging from tests

* chore: fix dep-check

* chore: rename strategies, add unixfs path traversal

* docs: fix doc-check in @helia/car

* chore: cleanup traversal & exporter options

* chore: apply suggestions from self code review

* chore: fix lint

* chore: fix dep-check

* chore: fix spellcheck

---------

Co-authored-by: Alex Potsides <alex@achingbrain.net>

The fleek deployment is no longer active

To make it easier to customise the default Helia settings, export a `heliaDefaults` function similar to the existing `libp2pDefaults` function.

If the helia routing fails to put or get a record, propagate that
failure to the caller, same as the local store/pubusb routings.

* chore: add or force update .github/workflows/stale.yml

* chore: add or force update .github/workflows/generated-pr.yml

For when you know that certain peers have some or all of the blocks
you want, allow passing providers to session implemenations to start
from instead of always querying the routing/connected peers.

```js
const buf = await helia.blocks.get(cid, {
  providers: [
    peerId1,
    peerId2
  ]
})
```

Session implementations accept an array of `PeerId | Multiaddr | Multiaddr[]`
and use them if they can or discard them if they can't.