filecoin-project / filecoin-project/boost

QueryAsk v2 Protocol

Open
#666 15 comments 0 reactions 1 assignee Claimed by @hannahhoward View on GitHub
kind/discussion kind/enhancement need/community-input need/team-input
Dominant language
Go
Stars
121
Forks
79
Avg merge
10d 14h
Merged PRs (30d)
1

Description

# Goals

Enable discoverability of HTTP retrieval support

The primary changes for v2 protocol are:

Query:
- You can ask for just a PieceCID (only piece retrieval protocols will be returned)

Response:
- Information will be given about available protocols, and parameters specific to those protocols

For now the newly design protocol makes all additional information protocol specific

# How

- probably make a new retrievalmarket folder to collect newly built retrieval pieces
- make an implementation of the [query protocol for libp2p](../tree/main/storagemarket/lp2pimpl), also drawing from [retrieval query protocol v1](https://github.com/filecoin-project/go-fil-markets/tree/master/retrievalmarket/network)

The schema for the QueryAsk v1 request / response (in IPLD schema -- it's encoded as DAG CBOR) is as follows:

```ipldsch
# QueryParams - V1 - indicate what specific information about a piece that a retrieval
# client is interested in, as well as specific parameters the client is seeking
# for the retrieval deal
type QueryParams struct {
PieceCID nullable Link # optional, query if miner has this cid in this piece. some miners may not be able to respond.
}

# Query is a query to a given provider to determine information about a piece
# they may have available for retrieval
type Query struct {
PayloadCID Link
QueryParams QueryParams
}

# QueryResponseStatus indicates whether a queried piece is available
type QueryResponseStatus enum {
# QueryResponseAvailable indicates a provider has a piece and is prepared to
# return it
| QueryResponseAvailable ("0")

# QueryResponseUnavailable indicates a provider either does not have or cannot
# serve the queried piece to the client
| QueryResponseUnavailable ("1")

# QueryResponseError indicates something went wrong generating a query response
| QueryResponseError ("2")
} representation int

# QueryItemStatus (V1) indicates whether the requested part of a piece (payload or selector)
# is available for retrieval
type QueryItemStatus enum {
# QueryItemAvailable indicates requested part of the piece is available to be
# served
| QueryItemAvailable ("0")

# QueryItemUnavailable indicates the piece either does not contain the requested
# item or it cannot be served
| QueryItemUnavailable ("1")

# QueryItemUnknown indicates the provider cannot determine if the given item
# is part of the requested piece (for example, if the piece is sealed and the
# miner does not maintain a payload CID index)
| QueryItemUnknown ("2")
} representation int

type Address Bytes
type TokenAmount Bytes

# QueryResponse is a miners response to a given retrieval query
type QueryResponse struct {
Status QueryResponseStatus
PieceCIDFound QueryItemStatus # V1 - if a PieceCID was requested, the result

Size Int

PaymentAddress Address # address.Address to send funds to -- may be different than miner addr
MinPricePerByte TokenAmount
MaxPaymentInterval Int
MaxPaymentIntervalIncrease Int
Message String
UnsealPrice TokenAmount
}
```

The proposed v2 schema is:

```ipldsch

# QueryKind specifies whether you are interested in a payload or a piece
type QueryKind enum {
| Piece ("pc")
| Payload ("pl")
} representation string

# Query is a query to a given provider to determine information about a piece
# they may have available for retrieval
type Query struct {
Kind QueryKind
# If kind is Payload, response will error if not included
PayloadCID optional Link
# If kind is Piece, response will error if not included
PieceCID optional Link
}

# QueryResponseStatus indicates whether a queried piece is available
type QueryResponseStatus enum {
# QueryResponseAvailable indicates a provider has a piece and is prepared to
# return it
| QueryResponseAvailable ("0")

# QueryResponseUnavailable indicates a provider either does not have or cannot
# serve the queried piece to the client
| QueryResponseUnavailable ("1")

# QueryResponseError indicates something went wrong generating a query response
| QueryResponseError ("2")
} representation int

# QueryItemStatus (V1) indicates whether the requested part of a piece (payload or selector)
# is available for retrieval
type QueryItemStatus enum {
# QueryItemAvailable indicates requested part of the piece is available to be
# served
| QueryItemAvailable ("0")

# QueryItemUnavailable indicates the piece either does not contain the requested
# item or it cannot be served
| QueryItemUnavailable ("1")

# QueryItemUnknown indicates the provider cannot determine if the given item
# is part of the requested piece (for example, if the piece is sealed and the
# miner does not maintain a payload CID index)
| QueryItemUnknown ("2")
} representation int

type Address Bytes
type TokenAmount Bytes

type ProtocolName enum {
| GraphsyncFIlecoinV1 ("graphsync/v1")
| HTTPFilecoinV1 ("http/v1")
} representation string

# QueryResponse is a miners response to a given retrieval query
type QueryResponse struct {
Status QueryResponseStatus
Protocols {ProtocolName:Any}
}

# Structure of Graphsync Protocol Data
type GraphsyncFilecoinV1Response struct {
Size Int
PaymentAddress Address # address.Address to send funds to -- may be different than miner addr
MinPricePerByte TokenAmount
MaxPaymentInterval Int
MaxPaymentIntervalIncrease Int
Message String
UnsealPrice TokenAmount
}

# Structure of HTTP V1 Response
type HTTPFilecoinV1Response {
URL String
Size Int
}
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.