uri-register 0.3.0

// Copyright TELICENT LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use crate::error::Result;
use async_trait::async_trait;

/// A service for registering URIs and assigning unique integer IDs
///
/// This trait defines the interface for a URI register service that maintains
/// a global mapping between URIs (strings) and integer IDs. It's designed for
/// use in distributed systems where multiple stateless compute nodes need
/// fast access to consistent URI-to-ID mappings.
///
/// ## Performance Considerations
///
/// - Always prefer `register_uri_batch()` over `register_uri()` for multiple URIs
/// - Batch operations are significantly more efficient (single database round-trip)
/// - Single operations may be slower due to multiple round-trips internally
#[async_trait]
pub trait UriService: Send + Sync {
    /// Register a single URI and return its ID
    ///
    /// If the URI already exists, returns the existing ID.
    /// If the URI is new, creates a new ID and returns it.
    ///
    /// For better performance with multiple URIs, use `register_uri_batch()` instead.
    ///
    /// # Arguments
    ///
    /// * `uri` - The URI string to register
    ///
    /// # Returns
    ///
    /// The unique integer ID assigned to this URI
    async fn register_uri(&self, uri: &str) -> Result<u64>;

    /// Register multiple URIs in batch and return their IDs
    ///
    /// For each URI:
    /// - If it exists, returns the existing ID
    /// - If it doesn't exist, creates a new ID
    ///
    /// # Order Preservation
    ///
    /// The returned vector maintains strict order correspondence with the input:
    /// `ids[i]` is the ID for `uris[i]`
    ///
    /// This is the recommended way to register multiple URIs - it's much faster
    /// than calling `register_uri()` multiple times.
    ///
    /// # Arguments
    ///
    /// * `uris` - Slice of URI strings to register
    ///
    /// # Returns
    ///
    /// Vector of IDs in the same order as the input URIs
    async fn register_uri_batch(&self, uris: &[String]) -> Result<Vec<u64>>;

    /// Register multiple URIs in batch and return a HashMap of URI-to-ID mappings
    ///
    /// For each URI:
    /// - If it exists, returns the existing ID
    /// - If it doesn't exist, creates a new ID
    ///
    /// # When to Use This
    ///
    /// Use this method when you need URI-to-ID mappings but don't care about order.
    /// This is slightly more efficient than `register_uri_batch()` because it doesn't
    /// need to maintain order correspondence.
    ///
    /// # Arguments
    ///
    /// * `uris` - Slice of URI strings to register
    ///
    /// # Returns
    ///
    /// HashMap mapping each URI to its assigned ID. Duplicate URIs in the input
    /// will only appear once in the output.
    async fn register_uri_batch_hashmap(
        &self,
        uris: &[String],
    ) -> Result<std::collections::HashMap<String, u64>>;
}