ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! [`BlobLocation`] — A citizen of [`AsyncLocate::Location`](super::AsyncLocate::Location), and never THE law.

use smol_bytes::Utf8Bytes;

use crate::ToGraphqlOutput;

#[cfg(test)]
mod tests;

/// WHERE a blob is, in the shape a backend with nothing more to say elects.
///
/// # It is A citizen of the seat, not the seat's definition
///
/// [`AsyncLocate::Location`](super::AsyncLocate::Location) is BARE: the backend defines what a location IS,
/// and a store that knows an etag, a generation, a bucket or a signed expiry writes its OWN type
/// carrying them. This one exists so that a backend which knows only the address — the shipped
/// filesystem store is exactly that — does not have to mint a struct to say so, and so that the
/// crate has one worked example of a location crossing the wire.
///
/// Nothing here is privileged. No framework path asks for this type, no bound names it, and a
/// backend electing its own pays nothing for declining it. That is the whole difference between a
/// convenience and a law, and it is why the seat above carries no bound: a bound would have made
/// this shape the only shape.
///
/// # The ADDRESS is text, and the rest is optional because a pure render cannot invent it
///
/// [`address`](Self::address) is the one member that is always there — it is the part a client
/// round-trips, and it is the part derivable from the key alone.
/// [`size`](Self::size) and [`content_type`](Self::content_type) are `Option`, and the reason is
/// [`AsyncLocate::location`](super::AsyncLocate::location)'s pin rather than modesty: describing an address
/// does NO I/O, so a fact only a `stat` or a `HEAD` could supply is a fact this type reports as
/// absent. A backend that already holds one — because its manifest carries it, or because its
/// listing returned it — fills it in; the shipped filesystem store does not, and leaves both unsaid.
///
/// A member that is structurally unknowable to one backend and ordinary to another is exactly what
/// `Option` is for, and it is why those two are not on the [`AsyncLocate`](super::AsyncLocate) seat itself.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BlobLocation {
  address: Utf8Bytes,
  content_type: Option<Utf8Bytes>,
  size: Option<u64>,
}

impl BlobLocation {
  /// A location at `address`, with nothing further said about it.
  #[inline]
  #[must_use]
  pub fn new(address: impl Into<Utf8Bytes>) -> Self {
    Self {
      address: address.into(),
      content_type: None,
      size: None,
    }
  }

  /// The same location, carrying the media type a backend already knows.
  ///
  /// Consuming rather than a setter, so a backend builds its answer in one expression and no
  /// half-filled location is ever a value some later line may or may not have finished.
  #[inline]
  #[must_use]
  pub fn with_content_type(mut self, content_type: impl Into<Utf8Bytes>) -> Self {
    self.content_type = Some(content_type.into());
    self
  }

  /// The same location, carrying the byte length a backend already knows.
  ///
  /// It is NOT a licence to go and measure — see the type note: this member exists for a store whose
  /// answer already contained the number.
  #[inline]
  #[must_use]
  pub const fn with_size(mut self, size: u64) -> Self {
    self.size = Some(size);
    self
  }

  /// The address, as text — the part a client round-trips.
  #[inline]
  #[must_use]
  pub fn address(&self) -> &str {
    &self.address
  }

  /// The media type, where the backend knew one.
  #[inline]
  #[must_use]
  pub fn content_type(&self) -> Option<&str> {
    self.content_type.as_deref()
  }

  /// The byte length, where the backend knew one.
  #[inline]
  #[must_use]
  pub const fn size(&self) -> Option<u64> {
    self.size
  }
}

// The wire face, hand-written for the reason `ingraph-codegen`'s `emit::wire` writes its own: a
// derive would publish this type's rustdoc as schema descriptions, and a description is a schema
// commitment rather than a side effect of documenting Rust.
//
// Which is also why this note is `//` and not `///`. `#[Object]` calls `get_rustdoc` on the BLOCK
// and on every method with no key to decline it, so a doc comment here does not document the impl —
// it publishes itself into the SDL as `type BlobLocation`'s description. Measured, by reading a
// schema that had one.
//
// The method idents wear `__async_graphql_` and every field spells `#[graphql(name = "…")]`, which
// is the ruled pin AND, here, forced twice over: an `async fn address` in this block would be a
// second definition of the inherent `address` above (`E0592`), and the library's own camelCase
// fallback over a prefixed ident would publish `asyncGraphqlAddress` — a name no client wants to
// read, and the reason layer 3 is written out on every field rather than on the renamed ones.
//
// The prefix names the BACKEND, per the ruling of 2026-08-13, so a second GraphQL binding on this
// same type mints `__smear_address` beside these three and neither face is the reason the other
// cannot be written. `ingraph-codegen`'s `method::wire_method` is the emitted half's one door; this
// is the library's own face wearing what it emits.
#[cfg(feature = "async-graphql")]
#[async_graphql::Object(name = "BlobLocation")]
impl BlobLocation {
  #[graphql(name = "address")]
  async fn __async_graphql_address(&self) -> &str {
    self.address()
  }

  #[graphql(name = "contentType")]
  async fn __async_graphql_content_type(&self) -> Option<&str> {
    self.content_type()
  }

  #[graphql(name = "size")]
  async fn __async_graphql_size(&self) -> Option<u64> {
    self.size()
  }
}

/// The OUTPUT CROSSING: a location is returned BY REFERENCE, the identity row every type that
/// already has a wire face takes.
///
/// The row lives beside the type rather than in
/// [`graphql::output`](crate::ToGraphqlOutput)'s own table because it is what a BACKEND's location
/// row will look like — the trait is `ingraph`'s and the type is the implementer's, so the impl is
/// ordinary local work with no orphan rule anywhere near it. That this crate's own citizen writes
/// exactly the row a third party writes is the point.
impl ToGraphqlOutput for BlobLocation {
  type Output<'a> = &'a Self;

  #[inline]
  fn to_graphql_output(marked: &Self) -> &Self {
    marked
  }
}