sley_remote/
lib.rs

1//! `git-remote` — callable fetch / push / clone / ls-remote orchestration.
2//!
3//! This crate lifts the network-transport orchestration out of the `git-cli`
4//! monolith so it can be driven as a library (the way a downstream consumer such
5//! as heddle needs). The wire codecs ([`sley_protocol`]), the pack encoder
6//! ([`sley_pack`]), pack building ([`sley_odb`]) and ref/commit plumbing already
7//! live in their own crates; `git-remote` is the glue that sequences them into
8//! `fetch`/`push`/`clone`/`ls-remote`, with the CLI-specific concerns (argument
9//! parsing, stdout/stderr formatting, exit codes, repository discovery from
10//! process-global state) kept out via the seams below:
11//!
12//! * [`CredentialProvider`] — how authenticated remotes obtain credentials. The
13//!   caller injects one (e.g. a credential-helper-backed impl, an interactive
14//!   prompt, or [`NoCredentials`] for unauthenticated/public access).
15//! * [`ProgressSink`] — where human-facing progress/summary lines go. The
16//!   orchestration returns structured outcomes and emits progress through this
17//!   sink instead of printing, so the caller controls presentation.
18//!
19//! The lift proceeds in stages (see `docs/git-remote-extraction.md`); this is
20//! the scaffold (stage A).
21
22use std::path::Path;
23
24use sley_config::GitConfig;
25use sley_core::{ObjectFormat, Result};
26use sley_transport::GitCredential;
27
28mod credentials;
29pub use credentials::{
30    CredentialHelperProvider, credential_fill, credential_request_for_url, credential_store,
31    http_credential_host, http_protocol_name, http_url_credential,
32};
33
34#[cfg(feature = "http")]
35mod http;
36#[cfg(feature = "http")]
37pub use http::{
38    HttpFetchPackRequest, HttpServiceAdvertisements, http_advertised_refs,
39    http_authorization_headers, http_check_status, http_protocol_v2_fetch_response,
40    http_send_with_auth, http_service_advertisements, http_upload_pack_advertisements,
41    http_validate_content_type, install_fetch_pack_via_http_protocol_v2_fetch,
42    install_fetch_pack_via_http_upload_pack, new_http_client, remote_url_is_http,
43};
44
45mod ssh;
46pub use ssh::{
47    SshFetchPackRequest, SshTransportOptions, install_fetch_pack_via_ssh_upload_pack, ssh_program,
48    ssh_transport_options_from_config, ssh_upload_pack_advertisements,
49    ssh_upload_pack_advertisements_with_options,
50};
51
52mod git;
53pub use git::{
54    GitFetchPackRequest, git_upload_pack_advertisements,
55    git_upload_pack_advertisements_with_protocol, install_fetch_pack_via_git_upload_pack,
56};
57
58mod local;
59pub use local::{
60    INFINITE_DEPTH, LocalDeepenPlan, attach_receive_pack_capabilities,
61    attach_upload_pack_capabilities, compute_local_deepen, compute_local_deepen_by_rev_list,
62    install_fetch_pack_via_local_upload_pack, local_fetch_advertisements, local_have_oids,
63    receive_pack_features, receive_pack_into_local_repository,
64    receive_pack_request_uses_push_options, receive_pack_stream_into_local_repository,
65    serve_upload_pack_v2, serve_upload_pack_v2_with_config, upload_pack_features,
66    upload_pack_from_local_repository, upload_pack_request_uses_sideband,
67    upload_pack_sideband_response,
68};
69
70mod fetch;
71pub use fetch::{
72    FetchOptions, FetchOutcome, FetchRequest, FetchServices, FetchSource, PruneRefsInput,
73    PrunedRef, append_reachable_auto_follow_tags, apply_configured_fetch_prune_option,
74    apply_configured_remote_tag_option, fetch, fetch_head_source_description,
75    fetch_refspec_excludes, fetch_refspecs_for_source, mark_tag_refspec_updates_not_for_merge,
76    order_bundle_fetch_all_tags_updates, prune_refs_from_advertisements,
77    retain_missing_auto_follow_tags, write_default_fetch_head, write_fetch_head,
78    write_fetch_head_records,
79};
80
81mod pack;
82pub use pack::{
83    PushPackRequest, build_push_packfile, build_receive_pack_body,
84    remote_advertisement_tips_known_to_local,
85};
86
87mod push;
88pub use push::{
89    PushAction, PushActionPlan, PushActionRequest, PushCommand, PushDestination, PushOptions,
90    PushOutcome, PushPlan, PushRefStatus, PushReportRef, PushReportRequest, PushRequest,
91    PushServices, PushStatusReport, execute_push_action_plan, execute_push_plan,
92    local_push_source_refs, normalize_push_refname, normalize_push_refspec, plan_push,
93    plan_push_actions, push, push_actions, push_local_with_report, reject_non_fast_forward_pushes,
94    validate_receive_pack_report,
95};
96
97mod ls_remote;
98pub use ls_remote::{LsRemoteFilter, LsRemoteRecord, LsRemoteSource, ls_remote};
99
100mod clone;
101pub use clone::{CloneOptions, CloneOutcome, CloneRequest, CloneServices, CloneSource, clone};
102
103mod bundle;
104pub use bundle::{FetchBundleRequest, fetch_bundle};
105
106mod shallow;
107pub use shallow::{apply_shallow_info, read_shallow, write_shallow};
108
109mod capabilities;
110pub use capabilities::{
111    BUNDLE_FETCH_SUPPORTED, HTTP_PROTOCOL_V2_FETCH, RemoteTransportKind, SSH_CLONE_SUPPORTED,
112    THIN_PACK_PUSH_SUPPORTED, TransportCapabilities,
113};
114
115mod protocol;
116pub use protocol::{
117    TransportPolicyError, check_transport_allowed, is_transport_allowed,
118    transport_scheme_for_remote, transport_scheme_for_url,
119};
120
121mod resolve;
122pub use resolve::{
123    fetch_source_for_url, fetch_url, push_destination_for_url, push_url, resolve_fetch_source,
124    resolve_push_destination, transport_kind_for_url,
125};
126
127/// The object format of the repository whose common `$GIT_DIR` is `common_git_dir`.
128///
129/// Reads `common_git_dir/config`'s `extensions.objectFormat`, defaulting to
130/// SHA-1 when the config is absent or unreadable (matching git). `common_git_dir`
131/// must already be the common git dir; this does no worktree resolution.
132pub fn object_format_for_git_dir(common_git_dir: &Path) -> Result<ObjectFormat> {
133    let Ok(config) = GitConfig::read(common_git_dir.join("config")) else {
134        return Ok(ObjectFormat::Sha1);
135    };
136    config.repository_object_format()
137}
138
139/// Supplies credentials for an authenticated remote, mirroring git's credential
140/// protocol: [`fill`](CredentialProvider::fill) is handed a partial
141/// [`GitCredential`] describing the request (protocol/host/path) and returns a
142/// completed credential, or `None` to proceed unauthenticated.
143///
144/// [`approve`](CredentialProvider::approve) / [`reject`](CredentialProvider::reject)
145/// let a backing store remember or forget a credential after the request
146/// succeeds or fails; the default no-ops suit providers without a store.
147pub trait CredentialProvider {
148    /// Complete `request` into a usable credential, or return `None` to attempt
149    /// the request without authentication.
150    fn fill(&mut self, request: GitCredential) -> Result<Option<GitCredential>>;
151
152    /// Record `credential` as having worked (e.g. store it). Default: no-op.
153    fn approve(&mut self, _credential: &GitCredential) -> Result<()> {
154        Ok(())
155    }
156
157    /// Record `credential` as having failed (e.g. erase it). Default: no-op.
158    fn reject(&mut self, _credential: &GitCredential) -> Result<()> {
159        Ok(())
160    }
161}
162
163/// A [`CredentialProvider`] that never supplies credentials, so every request is
164/// attempted unauthenticated. This is what an embedder targeting public remotes
165/// (e.g. heddle) uses to suppress prompts.
166#[derive(Debug, Default, Clone, Copy)]
167pub struct NoCredentials;
168
169impl CredentialProvider for NoCredentials {
170    fn fill(&mut self, _request: GitCredential) -> Result<Option<GitCredential>> {
171        Ok(None)
172    }
173}
174
175/// Receives human-facing progress and summary events from an operation (the
176/// "To <remote>" push summary, prune notices, "Cloning into…", etc.). The
177/// orchestration returns structured outcomes regardless; this is purely for
178/// presentation, so the default implementations discard everything.
179pub trait ProgressSink {
180    /// A free-form progress or summary line.
181    fn message(&mut self, _message: &str) {}
182}
183
184/// A [`ProgressSink`] that discards every event.
185#[derive(Debug, Default, Clone, Copy)]
186pub struct SilentProgress;
187
188impl ProgressSink for SilentProgress {}
189
190#[cfg(test)]
191mod tests {
192    use super::*;
193    use std::fs;
194    use std::path::{Path, PathBuf};
195    use std::sync::atomic::{AtomicU64, Ordering};
196
197    use sley_config::{ConfigEntry, ConfigSection};
198    use sley_formats::RepositoryLayout;
199    use sley_object::{Commit, EncodedObject, ObjectType, Tree};
200    use sley_odb::{FileObjectDatabase, ObjectWriter};
201    use sley_refs::{FileRefStore, RefTarget, RefUpdate};
202    use sley_transport::{RemoteUrl, parse_remote_url};
203
204    #[test]
205    fn no_credentials_never_fills() {
206        let mut provider = NoCredentials;
207        let request = GitCredential::default();
208        assert!(
209            provider
210                .fill(request)
211                .expect("test operation should succeed")
212                .is_none()
213        );
214    }
215
216    #[test]
217    fn silent_progress_accepts_messages() {
218        let mut progress = SilentProgress;
219        progress.message("Cloning into 'x'...");
220    }
221
222    static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
223
224    fn live_env(name: &str) -> Option<String> {
225        match std::env::var(name) {
226            Ok(value) if !value.is_empty() => Some(value),
227            _ => None,
228        }
229    }
230
231    fn live_repo(name: &str) -> PathBuf {
232        let dir = std::env::temp_dir().join(format!(
233            "sley-remote-live-{name}-{}-{}",
234            std::process::id(),
235            TEMP_COUNTER.fetch_add(1, Ordering::Relaxed)
236        ));
237        let _ = fs::remove_dir_all(&dir);
238        RepositoryLayout::init_at(&dir, ObjectFormat::Sha1, false)
239            .expect("live test repository should initialize");
240        dir.join(".git")
241    }
242
243    fn remote_config(url: &str) -> GitConfig {
244        GitConfig {
245            sections: vec![ConfigSection::new(
246                "remote",
247                Some("origin".into()),
248                vec![
249                    ConfigEntry::new("url", Some(url.into())),
250                    ConfigEntry::new("fetch", Some("+refs/heads/*:refs/remotes/origin/*".into())),
251                ],
252            )],
253            ..GitConfig::default()
254        }
255    }
256
257    fn fetch_options(depth: Option<u32>) -> FetchOptions {
258        FetchOptions {
259            quiet: true,
260            auto_follow_tags: false,
261            fetch_all_tags: false,
262            prune: false,
263            prune_tags: false,
264            dry_run: false,
265            append: false,
266            write_fetch_head: true,
267            tag_option_explicit: true,
268            prune_option_explicit: true,
269            prune_tags_option_explicit: true,
270            refmap: None,
271            depth,
272            merge_srcs: Vec::new(),
273            filter: None,
274            refetch: false,
275            cloning: false,
276            record_promisor_refs: true,
277            update_shallow: false,
278            deepen_relative: false,
279            update_head_ok: false,
280            deepen_since: None,
281            deepen_not: Vec::new(),
282            ssh_options: None,
283            atomic: false,
284        }
285    }
286
287    fn write_live_commit(git_dir: &Path, branch: &str) {
288        let format = ObjectFormat::Sha1;
289        let db = FileObjectDatabase::from_git_dir(git_dir, format);
290        let tree = db
291            .write_object(EncodedObject::new(
292                ObjectType::Tree,
293                Tree { entries: vec![] }.write(),
294            ))
295            .expect("live commit tree should write");
296        let timestamp = 1 + TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
297        let identity =
298            format!("Sley Remote Live <sley@example.invalid> {timestamp} +0000").into_bytes();
299        let oid = db
300            .write_object(EncodedObject::new(
301                ObjectType::Commit,
302                Commit {
303                    tree,
304                    parents: Vec::new(),
305                    author: identity.clone(),
306                    committer: identity,
307                    encoding: None,
308                    message: format!("sley remote live {branch}\n").into_bytes(),
309                }
310                .write(),
311            ))
312            .expect("live commit should write");
313        let store = FileRefStore::new(git_dir, format);
314        let mut tx = store.transaction();
315        tx.update(RefUpdate {
316            name: format!("refs/heads/{branch}"),
317            expected: None,
318            new: RefTarget::Direct(oid),
319            reflog: None,
320        });
321        tx.update(RefUpdate {
322            name: "HEAD".into(),
323            expected: None,
324            new: RefTarget::Symbolic(format!("refs/heads/{branch}")),
325            reflog: None,
326        });
327        tx.commit().expect("live refs should update");
328    }
329
330    struct EnvCredentials {
331        username: String,
332        password: String,
333    }
334
335    impl CredentialProvider for EnvCredentials {
336        fn fill(&mut self, mut request: GitCredential) -> Result<Option<GitCredential>> {
337            request.username = Some(self.username.clone());
338            request.password = Some(self.password.clone());
339            Ok(Some(request))
340        }
341    }
342
343    fn live_fetch(
344        url_var: &str,
345        branch_var: &str,
346        source: FetchSource,
347        credentials: &mut dyn CredentialProvider,
348        depth: Option<u32>,
349    ) {
350        let Some(url) = live_env(url_var) else {
351            return;
352        };
353        let branch = live_env(branch_var).unwrap_or_else(|| "main".into());
354        let local = live_repo(url_var);
355        let refspec = format!("refs/heads/{branch}:refs/remotes/origin/{branch}");
356        let config = remote_config(&url);
357        let options = fetch_options(depth);
358        let mut progress = SilentProgress;
359
360        let outcome = fetch(
361            FetchRequest {
362                git_dir: &local,
363                format: ObjectFormat::Sha1,
364                config: &config,
365                remote_name: "origin",
366                source: &source,
367                refspecs: &[refspec],
368                options: &options,
369            },
370            FetchServices {
371                credentials,
372                progress: &mut progress,
373                ref_hook: None,
374            },
375        )
376        .expect("live fetch should succeed");
377
378        assert!(!outcome.ref_updates.is_empty());
379        if depth.is_some() {
380            assert!(
381                local.join("shallow").exists(),
382                "shallow fetch should write .git/shallow"
383            );
384        }
385    }
386
387    fn live_push(
388        url_var: &str,
389        branch_prefix_var: &str,
390        destination: PushDestination,
391        credentials: &mut dyn CredentialProvider,
392    ) {
393        let Some(_) = live_env(url_var) else {
394            return;
395        };
396        let branch_prefix =
397            live_env(branch_prefix_var).unwrap_or_else(|| "sley-remote-live".into());
398        let branch = format!(
399            "{branch_prefix}-{}-{}",
400            std::process::id(),
401            TEMP_COUNTER.fetch_add(1, Ordering::Relaxed)
402        );
403        let local = live_repo(url_var);
404        write_live_commit(&local, &branch);
405        let refspec = format!("refs/heads/{branch}:refs/heads/{branch}");
406        let options = PushOptions {
407            quiet: true,
408            force: false,
409        };
410        let mut progress = SilentProgress;
411
412        let outcome = push(
413            PushRequest {
414                git_dir: &local,
415                common_git_dir: &local,
416                format: ObjectFormat::Sha1,
417                config: &GitConfig::default(),
418                remote: "origin",
419                destination: &destination,
420                refspecs: &[refspec],
421                options: &options,
422            },
423            PushServices {
424                credentials,
425                progress: &mut progress,
426            },
427        )
428        .expect("live push should succeed");
429
430        assert_eq!(outcome.commands.len(), 1);
431    }
432
433    #[test]
434    fn live_github_https_public_fetch() {
435        let Some(url) = live_env("SLEY_REMOTE_LIVE_GITHUB_HTTPS_PUBLIC_URL") else {
436            return;
437        };
438        let remote = parse_remote_url(&url).expect("live HTTPS URL should parse");
439        let mut credentials = NoCredentials;
440        live_fetch(
441            "SLEY_REMOTE_LIVE_GITHUB_HTTPS_PUBLIC_URL",
442            "SLEY_REMOTE_LIVE_GITHUB_HTTPS_PUBLIC_BRANCH",
443            FetchSource::Http(remote),
444            &mut credentials,
445            None,
446        );
447    }
448
449    #[test]
450    fn live_private_https_auth_fetch_uses_credential_provider() {
451        let (Some(url), Some(username), Some(password)) = (
452            live_env("SLEY_REMOTE_LIVE_PRIVATE_HTTPS_URL"),
453            live_env("SLEY_REMOTE_LIVE_PRIVATE_HTTPS_USERNAME"),
454            live_env("SLEY_REMOTE_LIVE_PRIVATE_HTTPS_PASSWORD"),
455        ) else {
456            return;
457        };
458        let remote = parse_remote_url(&url).expect("live private HTTPS URL should parse");
459        let mut credentials = EnvCredentials { username, password };
460        live_fetch(
461            "SLEY_REMOTE_LIVE_PRIVATE_HTTPS_URL",
462            "SLEY_REMOTE_LIVE_PRIVATE_HTTPS_BRANCH",
463            FetchSource::Http(remote),
464            &mut credentials,
465            None,
466        );
467    }
468
469    #[test]
470    fn live_https_push() {
471        let Some(url) = live_env("SLEY_REMOTE_LIVE_HTTPS_PUSH_URL") else {
472            return;
473        };
474        let remote = parse_remote_url(&url).expect("live HTTPS push URL should parse");
475        let mut no_credentials;
476        let mut env_credentials;
477        let credentials: &mut dyn CredentialProvider = match (
478            live_env("SLEY_REMOTE_LIVE_HTTPS_PUSH_USERNAME"),
479            live_env("SLEY_REMOTE_LIVE_HTTPS_PUSH_PASSWORD"),
480        ) {
481            (Some(username), Some(password)) => {
482                env_credentials = EnvCredentials { username, password };
483                &mut env_credentials
484            }
485            _ => {
486                no_credentials = NoCredentials;
487                &mut no_credentials
488            }
489        };
490        live_push(
491            "SLEY_REMOTE_LIVE_HTTPS_PUSH_URL",
492            "SLEY_REMOTE_LIVE_HTTPS_PUSH_BRANCH_PREFIX",
493            PushDestination::Http(remote),
494            credentials,
495        );
496    }
497
498    #[test]
499    fn live_ssh_fetch() {
500        let Some(url) = live_env("SLEY_REMOTE_LIVE_SSH_FETCH_URL") else {
501            return;
502        };
503        let remote = parse_remote_url(&url).expect("live SSH fetch URL should parse");
504        let mut credentials = NoCredentials;
505        live_fetch(
506            "SLEY_REMOTE_LIVE_SSH_FETCH_URL",
507            "SLEY_REMOTE_LIVE_SSH_FETCH_BRANCH",
508            FetchSource::Ssh(remote),
509            &mut credentials,
510            None,
511        );
512    }
513
514    #[test]
515    fn live_ssh_push() {
516        let Some(url) = live_env("SLEY_REMOTE_LIVE_SSH_PUSH_URL") else {
517            return;
518        };
519        let remote = parse_remote_url(&url).expect("live SSH push URL should parse");
520        let mut credentials = NoCredentials;
521        live_push(
522            "SLEY_REMOTE_LIVE_SSH_PUSH_URL",
523            "SLEY_REMOTE_LIVE_SSH_PUSH_BRANCH_PREFIX",
524            PushDestination::Ssh(remote),
525            &mut credentials,
526        );
527    }
528
529    #[test]
530    fn live_shallow_https_fetch_and_clone() {
531        let Some(url) = live_env("SLEY_REMOTE_LIVE_SHALLOW_HTTPS_URL") else {
532            return;
533        };
534        let branch =
535            live_env("SLEY_REMOTE_LIVE_SHALLOW_HTTPS_BRANCH").unwrap_or_else(|| "main".into());
536        let remote = parse_remote_url(&url).expect("live shallow HTTPS URL should parse");
537        let mut credentials = NoCredentials;
538        live_fetch(
539            "SLEY_REMOTE_LIVE_SHALLOW_HTTPS_URL",
540            "SLEY_REMOTE_LIVE_SHALLOW_HTTPS_BRANCH",
541            FetchSource::Http(remote.clone()),
542            &mut credentials,
543            Some(1),
544        );
545
546        let destination = std::env::temp_dir().join(format!(
547            "sley-remote-live-clone-{}-{}",
548            std::process::id(),
549            TEMP_COUNTER.fetch_add(1, Ordering::Relaxed)
550        ));
551        let _ = fs::remove_dir_all(&destination);
552        let config = remote_config(&url);
553        let mut configure = |_git_dir: &Path| Ok(config.clone());
554        let mut configure_branch = |_git_dir: &Path, _branch: &str| Ok(config.clone());
555        let options = CloneOptions {
556            origin: "origin",
557            checkout_branch: &branch,
558            remote_head_branch: &branch,
559            single_branch: true,
560            depth: Some(1),
561            deepen_since: None,
562            deepen_not: Vec::new(),
563            committer: b"Sley Remote Live <sley@example.invalid> 1 +0000".to_vec(),
564            detached_head: None,
565            checkout: true,
566            filter: None,
567            // The live test clones a specific branch via --single-branch, so the
568            // branch was explicitly requested (a missing remote tip is a hard error).
569            branch_explicit: true,
570            ref_storage: sley_formats::RefStorageFormat::Files,
571            ssh_options: None,
572        };
573        let mut clone_credentials = NoCredentials;
574        let mut progress = SilentProgress;
575
576        let outcome = clone(
577            CloneRequest {
578                destination: &destination,
579                git_dir_override: None,
580                core_worktree: None,
581                format: ObjectFormat::Sha1,
582                source: &CloneSource::Http(RemoteUrl { ..remote }),
583                options: &options,
584            },
585            CloneServices {
586                configure: &mut configure,
587                configure_branch: &mut configure_branch,
588                credentials: &mut clone_credentials,
589                progress: &mut progress,
590            },
591        )
592        .expect("live shallow HTTPS clone should succeed");
593
594        assert!(outcome.git_dir.join("shallow").exists());
595    }
596}
sley_remote/lib.rs

sley_remote/
lib.rs
